Sesiones

Crea una sesión de visualización en vivo, envía una invitación al cliente y consulta su estado. Las marcas de tiempo son ISO-8601 UTC (…Z).

Crear una sesión

Crea una sesión y su invitación, y luego envía el enlace de invitación por el channel elegido. Envía teamId con un JWT del panel; una clave de API implica su propio equipo.

curl -X POST https://api.seeitlive.io/v1/sessions \
  -H "Authorization: Bearer sil_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "recipientPhone": "+15555550123", "smsConsent": true, "note": "Ticket #4821" }'

inviteShortUrl es un alias corto sitl.cc/s/code de la inviteUrl del invitado, o null cuando no se generó ningún enlace corto. Los agentes siempre incrustan el agentViewUrl completo.

{
  "id": "f74f1305-2222-4a11-8b1e-1234567890ab",
  "status": "pending",
  "inviteCode": "aZ3kQ9",
  "inviteUrl": "https://seeitlive.io/u/aZ3kQ9#3n9F1Qk7xY2zR8vB5tW6uL0mC4pD1sA...",
  "inviteShortUrl": "https://sitl.cc/s/aB3xK9p2",
  "agentViewUrl": "https://seeitlive.io/a/pL2mN8#7dR2Xa4Wq9Kj6bV3nF1yT8sH5cE0uZ...",
  "protection": "totp",
  "protectionSecret": "JBSWY3DPEHPK3PXP",
  "protectionOtpauthUrl": "otpauth://totp/SeeItLive:session-aZ3kQ9?secret=JBSWY3DPEHPK3PXP&issuer=SeeItLive",
  "expiresAt": "2026-07-07T09:42:00.000Z"
}

Obtener una sesión

Devuelve una sesión, incluyendo su metadata y su invitación (código, expiración, hora de apertura, canal, destinatario) — nunca un hash de token ni el secreto del invitado. Requiere el permiso view_sessions en un JWT del panel, o un token de API/OAuth con el ámbito sessions:read. Devuelve 404 si la sesión no existe.

curl https://api.seeitlive.io/v1/sessions/f74f1305-2222-4a11-8b1e-1234567890ab \
  -H "Authorization: Bearer $SEEITLIVE_KEY"

{
  "id": "f74f1305-2222-4a11-8b1e-1234567890ab",
  "teamId": "b5a2b2b0-6c7a-4e2f-9f2a-1234567890ab",
  "env": "live",
  "status": "live",
  "createdByClientId": "9d8c7b6a-5f4e-3d2c-1b0a-abcdef123456",
  "createdByApiKeyId": null,
  "note": "Ticket #4821",
  "metadata": { "ticketId": "4821" },
  "startedAt": "2026-07-07T09:14:03.000Z",
  "endedAt": null,
  "createdAt": "2026-07-07T09:12:00.000Z",
  "invitation": {
    "code": "aZ3kQ9",
    "expiresAt": "2026-07-07T09:42:00.000Z",
    "openedAt": "2026-07-07T09:13:41.000Z",
    "channel": "sms",
    "recipient": "+15555550123"
  }
}

Estado de la sesión

Consulta este endpoint para saber cuándo el cliente está frente a la cámara.

status avanza de pending → ringing → live → ended a medida que el cliente se une y se retira, o pasa directamente a expired (la invitación nunca se abrió) o cancelled.

{
  "id": "f74f1305-2222-4a11-8b1e-1234567890ab",
  "status": "live",
  "startedAt": "2026-07-07T09:14:03.000Z",
  "endedAt": null,
  "producerCount": 1,
  "hasVideo": true
}

Proteger una sesión

Una sesión protegida pide al invitado un secreto que le comunicas por otro canal: normalmente el agente se lo dicta por teléfono. Con password el secreto es fijo durante toda la vida de la invitación. Con totp es un código de 6 dígitos que cambia cada 30 segundos; envía tu propia semilla base32 para mostrar el código actual en tus propias herramientas, o deja que la generemos.

Leer el secreto actual

Devuelve lo que el agente debe dictar: la contraseña, o el código del momento con los segundos que le quedan. La semilla TOTP solo se devuelve una vez, al crear la sesión.

{
  "type": "totp",
  "password": null,
  "code": "418205",
  "secondsRemaining": 17,
  "locked": false,
  "failedAttempts": 0
}

Definir la protección

Cambia el desafío de invitado de una sesión después de crearla. Omita protectionSecret y se genera uno automáticamente: una contraseña de 8 caracteres o una semilla TOTP base32. Devuelve la misma estructura que el GET anterior.

{
  "protection": "password",
  "protectionSecret": "K7QMX2RT"
}

Enviar {"protection": "none"} elimina el desafío y borra con él cualquier bloqueo. Cada cambio reinicia el contador de intentos fallidos, porque al cliente se le va a comunicar un secreto distinto.

Levantar un bloqueo

Cinco respuestas incorrectas bloquean la invitación. Esto levanta el bloqueo; pase rotate: true para generar además un secreto nuevo. La rotación es opcional porque la causa habitual es un error de tecleo, y un secreto nuevo solo obliga a dictarlo otra vez.

{
  "rotate": true
}

Desbloqueo del invitado

La página del invitado canjea la respuesta por un token de desbloqueo de corta duración, que después exige el handshake de señalización. Cinco respuestas incorrectas bloquean la invitación y devuelven 403 con code: "invitation_locked" hasta que un agente la desbloquee.

Envía el code de la invitación, su token (el fragmento de la URL de invitación) y la respuesta del cliente en answer: la contraseña, o el código de 6 dígitos del momento. Omite answer en una invitación sin protección.

{
  "code": "aZ3kQ9",
  "token": "3n9F1Qk7xY2zR8vB5tW6uL0mC4pD1sA...",
  "answer": "418205"
}

Si acierta, recibes una prueba de corta duración. Caduca a los 60 minutos, o con la invitación si esta expira antes, y deja de aceptarse en cuanto se renueva el secreto.

{
  "unlockToken": "sil_gu_eyJpIjoiOWQ4YzdiNmEiLCJlIjoxNzg1...",
  "expiresAt": "2026-08-05T10:42:00.000Z"
}

Reclamar la invitación

La página del invitado llama a este endpoint para autenticarse y hacer que la sesión suene en la pantalla del agente. Una invitación protegida debe presentar además el token unlock del paso anterior.

{
  "code": "aZ3kQ9",
  "token": "3n9F1Qk7xY2zR8vB5tW6uL0mC4pD1sA...",
  "unlock": "sil_gu_eyJpIjoiOWQ4YzdiNmEiLCJlIjoxNzg1..."
}

Sin él —o con una prueba emitida para otra invitación, o contra un secreto ya renovado— la llamada se rechaza con 403 y code: "protection_required", sin tocar la sesión.

{
  "statusCode": 403,
  "error": "ForbiddenError",
  "message": "This session is protected — enter the password or code first",
  "code": "protection_required"
}

Emitir un token de agente

Emite un nuevo token de vista de agente, válido durante 120 minutos, para una sesión a la que el emisor ya tiene acceso — úsalo para reincrustar el visor, por ejemplo tras la expiración del agentViewUrl original. Acepta un label opcional (1 a 64 caracteres) mostrado en la lista de visores del panel; si se omite, un emisor con clave de API u OAuth obtiene "Integration viewer", y un JWT del panel obtiene "Dashboard viewer". Requiere el permiso view_sessions en un JWT del panel, o un token de API/OAuth con el ámbito sessions:write.

curl -X POST https://api.seeitlive.io/v1/sessions/f74f1305-2222-4a11-8b1e-1234567890ab/agent-token \
  -H "Authorization: Bearer $SEEITLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Odoo — crm.lead 42" }'

{
  "code": "qR7mZ2",
  "token": "5aQ1nD8vC3xF6yK9bH2wS7pM4dJ0uT1gN...",
  "agentViewUrl": "https://seeitlive.io/a/qR7mZ2#5aQ1nD8vC3xF6yK9bH2wS7pM4dJ0uT1gN..."
}

Resolver una invitación (público)

El endpoint público que la página del invitado llama para resolver un code de invitación en su sesión y marca — no requiere token ni clave. Unirse a la transmisión se autentica por separado, con el token incorporado en el fragmento de la URL de invitación.

{
  "sessionId": "f74f1305-2222-4a11-8b1e-1234567890ab",
  "brand": {
    "name": "Acme Support",
    "brandLogoUrl": null,
    "brandColor": "#1a2b3c"
  },
  "status": "pending",
  "protection": "totp",
  "locked": false
}