Create Session

Establishes an authenticated session between the client app and the Vonage API. A valid session is required before making or receiving calls. The session lifetime is determined by the exp claim of the JWT used to create it.

Signature

// Callback version
fun createSession(
  token: String,
  callback: (Exception?, String?) -> Unit
)

fun createSession(
  token: String,
  sessionId: String?,
  callback: (Exception?, String?) -> Unit
)

// Suspend version
suspend fun createSession(token: String): String

suspend fun createSession(token: String, sessionId: String?): String

Parameters

Parameter	Type	Required	Description
token	String / string	Yes	A JWT minted by your custom backend. Must include sub, application_id, acl, and exp claims.
sessionId	String? / string?	No	A previously stored session ID. Pass this to reattach to a disconnected session — the backend retains the session for approximately 15 minutes after disconnect. If provided within approximately 30 seconds of the disconnect, the server additionally replays any pending events (such as call invites) that arrived during that shorter window; reattaching after 30 seconds still succeeds but without event replay.

Return Type

Returns a sessionId string identifying the new session.

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

Usage Example

Basic session creation

 // Callback
 client.createSession("token") { err, sessionId ->
     when {
         err != null -> {  } // handle error
         else -> println(sessionId)
     }
 }

 // Coroutine
 try {
     val session1 = client.createSession("token")
     println(session1)
 }
 catch (e:Error) {
     // Handle Error in creation session
 }

Reconnecting with a previous session ID

 // Callback
 client.createSession("token", "sessionId") { err, sessionId ->
     when {
         err != null -> {} // handle error
         else -> println(sessionId)
     }
 }

 // Coroutine
 try {
     val session1 = client.createSession("token", "sessionId")
     println(session1)
 } catch (e: Error) {
     // Handle Error in creation session
 }

Errors

This method can throw the following error types:

• SESSION_ERROR — expired token, invalid token, already active session, max sessions reached
• NETWORK_ERROR — socket transport failure, HTTP timeout, service unavailable
• INTERNAL_ERROR — authorization error, parsing failure
• UNKNOWN_ERROR — any unmapped exception

Notes

• Session lifetime is set by the JWT exp claim — there is no separate fixed TTL. To extend a session before the JWT expires, call refreshSession with a fresh JWT, or call createSession(jwt, existingSessionId) if you've lost SDK state and need to reattach. After a WebSocket disconnect, the backend retains the session for approximately 15 minutes so the client can reconnect — pass existingSessionId within that window. Note this is a separate, shorter window from event replay (see below): reconnecting after 30 seconds but within 15 minutes still succeeds, but pending events that arrived more than 30 seconds ago are no longer replayed.
• Register event listeners (such as onCallInvite) before calling createSession, so pending events are not missed.
• When passing a previous sessionId, the server replays pending events if reattached within approximately 30 seconds of the disconnect. This is a separate, shorter window than the ~15-minute session retention window above — reattaching after 30 seconds (but within 15 minutes) still succeeds, just without replayed events.
• Only one active session per client instance is allowed. Calling createSession while a session is active throws an error.

Related Actions

• deleteSession - End the current session
• serverCall - Make an outbound call (requires an active session)

Related Events

• onSessionError - Fired when a session error occurs
• onReconnecting - Fired when the session is reconnecting
• onReconnection - Fired when the session reconnects successfully