First outbound call

serverCall() starts an outbound call by sending call context to the Vonage API. The Vonage API then invokes your answer webhook with the context as custom_data, and your webhook returns an NCCO that decides routing.

Outbound flow

1. Client app calls serverCall(context).
2. Vonage API invokes your answer webhook with context as custom_data.
3. Your webhook returns NCCO.
4. Vonage API connects media to the callee.

Client snippet

 val context = mapOf(
     "to" to "sip:alice@example.com",
     "from" to "agent-123"
 )

 client.serverCall(context) { error, callId ->
     if (error != null) {
         println("Failed to start outbound call: $error")
         return@serverCall
     }

     println("Outbound call started, callId: $callId")
 }

Server answer webhook

INFO

The example below illustrates the required webhook response shape. Your actual implementation will vary based on your backend language and framework.

Your answer webhook must be publicly reachable and return valid NCCO.

connect endpoint type

Use "type": "app" in the connect endpoint to route the call to an SDK client by username. Use "type": "phone" to route to a PSTN number instead. See the NCCO connect endpoint types for all options.

const customData =
  (req.body.custom_data as { to?: string } | undefined) ?? {};
const destination = customData.to ?? 'callee-username';

const answerNcco = [
  {
    action: 'connect',
    endpoint: [
      {
        type: 'app',
        user: destination
      }
    ]
  }
];

res.json(answerNcco);

NCCO reference: Vonage NCCO docs

Handling errors

serverCall can fail if there is no active session, the call setup times out, or the Vonage API encounters an issue with your webhook. Always handle the error:

client.serverCall(context) { error, callId ->
    if (error != null) {
        println("Call failed: ${error.message}")
        // Common causes:
        // - No active session (call createSession first)
        // - Network timeout
        // - Answer webhook returned invalid NCCO
        return@serverCall
    }
    println("Call started: $callId")
}

For a full list of possible error types, see Errors.