Server Call

Starts an outbound voice call by sending context to your Voice API answer webhook. The backend decides call routing and NCCO behavior, and the SDK returns a callId used for further call control.

Signature

// Callback version
fun serverCall(
  context: Map<String, String>?,
  callback: (Exception?, String?) -> Unit
)

// Suspend version
suspend fun serverCall(
  context: Map<String, String>?
): String

Parameters

Parameter	Type	Required	Description
context	Platform-specific (see below)	No	Custom data forwarded to your backend answer webhook as call context

Context type by platform

Platform	Type	Example
Android (Kotlin)	Map<String, String>	mapOf("to" to "+14155550100")
Android (Java)	Map<String, String>	Map.of("to", "+14155550100")
iOS (Swift)	[String: String]	["to": "+14155550100"]
iOS (Obj-C)	NSDictionary<NSString *, NSString *> *	@{@"to": @"+14155550100"}
Web (TypeScript)	Record<string, unknown> (serialized as JSON)	{ to: "+14155550100" }

INFO

On native platforms (Android/iOS), context values must be strings. On Web, context is serialized as JSON and can contain nested objects, but string values are recommended for cross-platform consistency with your backend webhook.

Return Type

Returns a callId string for the outbound call.

serverCall resolves to Promise<string> on Web and returns String in native completion/async APIs.

Usage Example

// Callback

client.serverCall(mapOf("callee" to "user1")) { err, outboundCall ->
    when {
        err != null -> {} // handle error
        else -> println("CallId: $outboundCall")
    }
}

// Coroutine
try {
    val callId = client.serverCall(
        mapOf(
            "callee" to "user1"
        )
    )
    println("CallId: $callId")
} catch (e: Error) {
    // Handle Error in creation session
}

Errors

Error Type	Error Code	Description
SESSION_ERROR	Various session/auth codes	Session is not active or token/session state is invalid
CS_ERROR	Voice backend error codes	Backend rejected or failed while processing outbound call
NETWORK_ERROR	internal:error:serviceNotAvailable	Network failure, timeout, or service unavailability
INTERNAL_ERROR	Various internal codes	SDK-side parsing/state/media setup failure
UNKNOWN_ERROR	N/A	Unexpected failure that should be investigated

For complete error reference and handling guidelines, see Error Reference.

Notes

• serverCall requires a valid active session before it can succeed
• The context payload is application-defined and consumed by your backend webhook
• The returned callId is required for actions like hangup, mute, and say

Related Actions

• answer - Answer an inbound call invite
• reject - Reject an inbound call invite
• hangup - End an active voice call

Related Events

• onLegStatusUpdate - Fired when remote leg status changes
• onCallHangup - Fired when a call is terminated