Receive an inbound call
Inbound calls are delivered to clients with active sessions after the Vonage API executes your answer webhook flow.
Inbound path
Register listeners first
Register call invite listeners before creating or reconnecting a session, so incoming invites are not missed.
Handling inbound call invites
// Answer Call
client.setCallInviteListener {callId, from, channelType ->
println("Incoming Call from $from by channel $channelType")
client.answer(callId) {
it?.let {err ->
// Handle Error in answering call
println("Error in answering call: $err")
}
}
}
// Or reject the call:
// client.setCallInviteListener { callId, from, channelType ->
// client.reject(callId) {
// it?.let {err ->
// println("Error in rejecting call: $err")
// }
// }
// }
// Invite Cancelled
client.setCallInviteCancelListener { callId, reason ->
when (reason) {
VoiceInviteCancelReason.RemoteCancel -> println("Call Invite for call $callId was cancelled by the caller")
VoiceInviteCancelReason.AnsweredElsewhere -> println("Call Invite for call $callId was answered on another device")
VoiceInviteCancelReason.RejectedElsewhere -> println("Call Invite for call $callId was rejected on another device")
VoiceInviteCancelReason.RemoteTimeout -> println("Call Invite for call $callId timed out")
}
}
Invite cancel behavior
Invites can be canceled or time out before user action. Your app receives a cancel callback with one of the following reasons:
| Reason | Description |
|---|---|
RemoteCancel | The caller hung up before the invite was answered. |
RemoteTimeout | The invite expired on the Vonage API without user action. |
AnsweredElsewhere | The same user answered the call on another device or client instance. |
RejectedElsewhere | The same user rejected the call on another device or client instance. |
If the connection dropped while the invite was ringing, the SDK re-reads the invite after it reconnects and reports the cancel then. A ring timeout learned that way is reported as RemoteCancel.
UX guidance
- Dismiss incoming call UI immediately when any cancel reason arrives.
- Do not attempt to call
answer()orreject()after receiving a cancel event — the invite is no longer valid. - For multi-device scenarios (
AnsweredElsewhere/RejectedElsewhere), consider showing a brief toast or visual indicator so the user understands why the ringing stopped.
Handling errors
answer() and reject() can fail if the session has expired, the invite is no longer valid (already cancelled), or there is a network issue. Always handle the error callback to update your UI accordingly:
client.answer(callId) { error ->
if (error != null) {
// Answer failed — dismiss call UI and inform the user
println("Answer failed: ${error.message}")
// Common causes:
// - The session ended (connectionStatus is Disconnected)
// - Invite already cancelled by caller (voice:error:call_already_ended)
dismissIncomingCallUI()
return@answer
}
// Success — transition to active call UI
showActiveCallUI()
}
client.reject(callId) { error ->
if (error != null) {
// Reject failed — the invite may have already been cancelled
println("Reject failed: ${error.message}")
}
// In both success and failure, dismiss the incoming call UI
dismissIncomingCallUI()
}Recovery strategy
If answer() fails because the session ended (connectionStatus is Disconnected), call createSession with a valid JWT. Invites are not carried over to a new session, so the failed invite cannot be answered on it. If the invite has already been cancelled (voice:error:call_already_ended), there is no recovery — dismiss the UI and wait for the next invite. See Troubleshooting.
Further reading
- NCCO reference — full documentation for the JSON structure your answer webhook returns