Skip to content

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:

ReasonDescription
RemoteCancelThe caller hung up before the invite was answered.
RemoteTimeoutThe invite expired on the Vonage API without user action.
AnsweredElsewhereThe same user answered the call on another device or client instance.
RejectedElsewhereThe 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() or reject() 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:

kotlin
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

Built with VitePress.