Configuración de la sesión

Una sesión es una conexión autenticada entre tu aplicación cliente y la API de Vonage. Tu backend emite un JWT, y el Client SDK utiliza ese JWT en createSession().

Modelo de sesión

La API de Vonage controla el ciclo de vida de las sesiones.
El Client SDK no genera JWT ni gestiona la emisión de tokens.
Tu backend sigue siendo la fuente de referencia para las políticas de identidad y acceso.

Flujo de autenticación

Emisión de JWT en el backend

El ejemplo siguiente ilustra la estructura que debe tener un JWT. Tu implementación concreta variará en función del lenguaje y el marco de trabajo que utilices en el backend.

Los JWT deben generarse en tu servidor. La implementación concreta depende de la aplicación.

const privateKeyPem =
  '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----';

const payload: GuideJwtPayload = {
  application_id: applicationId,
  sub: userName,
  acl: {
    paths: {
      '/*/users/**': {},
      '/*/conversations/**': {},
      '/*/sessions/**': {},
      '/*/devices/**': {},
      '/*/image/**': {},
      '/*/media/**': {},
      '/*/applications/**': {}
    }
  },
  exp: Math.floor(Date.now() / 1000) + 60 * 60
};

const jwt = signJwt(payload, privateKeyPem);
console.log(jwt);

Crear una sesión

client.setConfig({ region: ConfigRegion.EU });

try {
  const sessionId = await client.createSession(jwt);
  console.log(`Session created: ${sessionId}`);
} catch (error) {
  console.error('Failed to create session', error);
}

 val client = VoiceClient(ctx)

 val config = VGClientConfig(VGConfigRegion.EU)
 client.setConfig(config)

 client.createSession(jwt) { error, sessionId ->
     if (error != null) {
         println("Failed to create session: $error")
         return@createSession
     }

     println("Session created: $sessionId")
 }

 VoiceClient client = VoiceClient.createClient(ctx);

 VGClientConfig config = new VGClientConfig(ClientConfigRegion.EU);
 client.setConfig(config);

 client.createSession(jwt, null, (error, sessionId) -> {
     if (error != null) {
         System.out.println("Failed to create session: " + error);
         return null;
     }

     System.out.println("Session created: " + sessionId);
     return null;
 });

 let config = VGClientConfig(region: .EU)
 client.setConfig(config)

 client.createSession(jwt) { error, sessionId in
     guard error == nil, let sessionId = sessionId else {
         print("Failed to create session: \(error?.localizedDescription ?? "unknown")")
         return
     }

     print("Session created: \(sessionId)")
 }

 VGClientConfig *config = [[VGClientConfig alloc] initWithRegion:VGConfigRegionEU];
 [client setConfig:config];

 [client createSession:jwt callback:^(NSError * _Nullable error, NSString * _Nullable sessionId) {
     if (error != nil || sessionId == nil) {
         NSLog(@"Failed to create session: %@", error);
         return;
     }

     NSLog(@"Session created: %@", sessionId);
 }];

Duración de la sesión

Una sesión permanece activa mientras dure el JWT utilizado en createSession() es válida. La duración de la sesión viene determinada por el JWT: exp solicitud: tu backend controla la duración de la misma (mínimo 30 segundos, máximo 24 horas; por defecto, 15 minutos si no se establece explícitamente). El SDK no impone ningún tiempo de vida (TTL) de sesión por sí mismo.

Para prolongar una sesión antes de que caduque su JWT, llama a refreshSession(jwt) con un JWT nuevo. Muchos clientes emiten JWT de corta duración (15 minutos) y los actualizan cada ~10 minutos desde su backend.

Restablecimiento de la conexión tras una desconexión temporal

Si el WebSocket se desconecta por cualquier motivo (pérdida de conexión, aplicación en suspenso, pestaña cerrada), el backend marca la sesión como desconectada, pero la mantiene activa durante aproximadamente 15 minutos para que el cliente pueda volver a conectarse. Durante ese intervalo:

Llame a refreshSession(jwt) si aún conservas el estado del SDK (el SDK realiza un seguimiento interno del ID de sesión).
O llama createSession(jwt, existingSessionId) si has perdido el estado del SDK (por ejemplo, al reiniciar la aplicación), pero has guardado tú mismo el identificador de sesión.

En ambos casos, el backend reproduce cualquier evento que se haya producido mientras estabas desconectado (invitaciones a llamadas entrantes, etc.), por lo que el cliente aún puede responder a una llamada que haya llegado durante el periodo de reconexión.

Si transcurren unos 15 minutos sin que se vuelva a establecer la conexión, la sesión se elimina y debes llamar al createSession(jwt) con un JWT nuevo para empezar uno nuevo.

Véase Sesiones del Vonage Client SDK Para obtener más información sobre el ciclo de vida de la sesión.

TTL de la sesión (15 minutos) y caducidad del JWT (exp (reclamación) son independientes. Un JWT puede tener una validez superior a 15 minutos, pero la sesión caduca de todos modos al cabo de 15 minutos, a menos que se actualice. Actualiza o vuelve a crear siempre la sesión antes de que expire el TTL.

Gestión de errores

createSession Puede fallar por varias razones. Gestiona siempre la llamada de retorno de error:

try {
  const sessionId = await client.createSession(token);
  console.log("Session created:", sessionId);
} catch (error) {
  // error is a VonageError with type and message
  console.error("Session creation failed:", error.type, error.message);
}

client.createSession(token) { error, sessionId ->
    if (error != null) {
        when {
            error.message?.contains("token") == true ->
                // Invalid or expired JWT — request a new one from your backend
                println("Token error: $error")
            error.message?.contains("already active") == true ->
                // Session already exists — call deleteSession first if you need a fresh session
                println("Session already active")
            else ->
                println("Session creation failed: $error")
        }
    } else {
        println("Session created: $sessionId")
    }
}

client.createSession(token) { error, sessionId in
    if let error = error {
        print("Session creation failed: \(error.localizedDescription)")
        return
    }
    print("Session created: \(sessionId ?? "")")
}

Para consultar una lista completa de los posibles tipos de error, véase Errores.