On Call Invite

Fired when an inbound call invite is received. Use this event to present incoming call UI and decide whether to answer or reject.

Event Registration

fun setCallInviteListener(
  fn: (callId: String, from: String, channelType: VoiceChannelType) -> Unit
): Subscription

Usage Example

 // Answer Call
 client.setCallInviteListener {inviteId, from, channelType ->
     println("Incoming Call from $from by channel $channelType")
     client.answer(inviteId) {
         it?.let {err ->
             // Handle Error in answering call
             println("Error in answering call: $err")
         }
     }
 }

 // Or reject the call:
 // client.setCallInviteListener { inviteId, from, channelType ->
 //     client.reject(inviteId) {
 //         it?.let {err ->
 //             println("Error in rejecting call: $err")
 //         }
 //     }
 // }

 // Invite Cancelled
 client.setCallInviteCancelListener { inviteId, reason ->
         when (reason) {
             VoiceInviteCancelReason.RemoteCancel -> println("Call Invite for call $inviteId was cancelled by the caller")
             VoiceInviteCancelReason.AnsweredElsewhere -> println("Call Invite for call $inviteId was answered on another device")
             VoiceInviteCancelReason.RejectedElsewhere -> println("Call Invite for call $inviteId was rejected on another device")
             VoiceInviteCancelReason.RemoteTimeout -> println("Call Invite for call $inviteId timed out")
         }
     }

Event Data

Parameter	Type	Description
callId	string	Unique call invite/call identifier
from	string	Caller identity
channelType	VoiceChannelType	Inbound channel type — see below

VoiceChannelType

Android / Web value	iOS value	Description
app	VGVoiceChannelTypeApp	In-app call
phone	VGVoiceChannelTypePhone	PSTN phone call
sip	VGVoiceChannelTypeSip	SIP call
websocket	VGVoiceChannelTypeWebsocket	WebSocket call

Notes

• This event is emitted for new inbound invites only
• Keep a strong reference to invite/call state in your application layer
• Invites may be canceled or timeout before user action

Context / Custom Data

The onCallInvite event does not include the context object that was passed to serverCall() by the caller. The invite only provides the callId, from (caller identity), and channelType.

If you need to pass custom data from caller to callee, include it in your NCCO answer webhook response (e.g. as custom headers) or retrieve it from your backend after the call is connected using the callId.

Related Actions

• answer - Accept the inbound invite
• reject - Decline the inbound invite

Related Events

• onCallInviteCancel - Fired when invite is canceled