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?): StringParameters
| 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, 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 timeNETWORK_ERROR— socket transport failure, HTTP timeout, service unavailableINTERNAL_ERROR— authorization error, parsing failureUNKNOWN_ERROR— any unmapped exception
For each code's cause and what to do, see Troubleshooting.
Notes
- Call
createSessiononce. 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
expclaim. The SDK has no session TTL of its own. To keep the session pastexp, callrefreshSessionwith a new JWT before it expires. - Register event listeners (such as
onCallInvite) before callingcreateSession, so pending events are not missed. - Calling
createSessionwhile 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; checkconnectionStatusand call it only when it isDisconnected. - If the connection cannot be opened,
createSessionkeeps retrying for up to 60 seconds, then fails withsession:error:websocket-transport-invalid.
Related Actions
deleteSession- End the current sessionserverCall- Make an outbound call (requires an active session)
Related Events
onSessionError- Fired when a session error occursonReconnecting- Fired when the session is reconnectingonReconnection- Fired when the session reconnects successfully