Skip to content

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 ​

ParameterTypeRequiredDescription
tokenString / stringYesA JWT minted by your custom backend. Must include sub, application_id, acl, and exp claims.
sessionIdString? / string?NoA previously stored session ID, for when the app process restarted. Vonage keeps a disconnected session for about 15 minutes, so passing its ID within that window reattaches to it. Pending events (such as call invites) are only replayed if you reattach within about 30 seconds. Pass null for a new session. You do not need this for drops while the app is running: the SDK reattaches on its own.

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, max sessions reached, session not confirmed in time
  • NETWORK_ERROR — socket transport failure, HTTP timeout, service unavailable
  • INTERNAL_ERROR — authorization error, parsing failure
  • UNKNOWN_ERROR — any unmapped exception

For each code's cause and what to do, see Troubleshooting.

Notes ​

  • Call createSession once. The SDK keeps the session connected and resumes it on its own after a drop or after the app was frozen, for up to 15 minutes. See Session lifecycle.
  • Session lifetime is set by the JWT exp claim. The SDK has no session TTL of its own. To keep the session past exp, call refreshSession with a new JWT before it expires.
  • Register event listeners (such as onCallInvite) before calling createSession, so pending events are not missed.
  • Calling createSession while a session exists replaces it: the SDK deletes the current session, then creates the new one. It does not throw. Calls in progress on the old session fail, so do not call it on every foreground or push; check connectionStatus and call it only when it is Disconnected.
  • If the connection cannot be opened, createSession keeps retrying for up to 60 seconds, then fails with session:error:websocket-transport-invalid.

Built with VitePress.