Sessions

Créez une session de visionnage en direct, envoyez une invitation au client et interrogez son statut. Les horodatages sont en ISO-8601 UTC (…Z).

Créer une session

Crée une session et son invitation, puis transmet le lien d'invitation via le channel choisi. Passez teamId avec un JWT de tableau de bord ; une clé API implique sa propre équipe.

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 est un alias court sitl.cc/s/code de l'inviteUrl invité, ou null si aucun lien court n'a été généré. Les agents intègrent toujours l'agentViewUrl complet.

{
  "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"
}

Récupérer une session

Renvoie une session, y compris ses metadata et son invitation (code, expiration, heure d'ouverture, canal, destinataire) — jamais un hachage de jeton ni le secret invité. Nécessite la permission view_sessions sur un JWT de tableau de bord, ou un jeton API/OAuth avec la portée sessions:read. Renvoie 404 si la session n'existe pas.

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"
  }
}

Statut de la session

Interrogez ce point de terminaison pour savoir quand le client est devant sa caméra.

status évolue de pending → ringing → live → ended au fur et à mesure que le client rejoint puis quitte, ou passe directement à expired (l'invitation n'a jamais été ouverte) ou cancelled.

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

Protéger une session

Une session protégée demande au client un secret que vous lui transmettez par un autre canal — en général, l'agent le lui dicte au téléphone. Avec password, le secret reste fixe pendant toute la durée de l'invitation. Avec totp, il change toutes les 30 secondes ; fournissez votre propre graine base32 pour afficher le code courant dans vos propres outils, ou laissez-nous en générer une.

Lire le secret courant

Renvoie ce que l'agent doit dicter : le mot de passe, ou le code du moment avec le nombre de secondes restantes. La graine TOTP elle-même est renvoyée une seule fois, à la création de la session.

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

Définir la protection

Modifie le défi invité d’une session après sa création. Omettez protectionSecret et il est généré pour vous — un mot de passe de 8 caractères, ou une graine TOTP base32. Renvoie la même structure que le GET ci-dessus.

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

Envoyer {"protection": "none"} retire le défi, et efface tout verrouillage avec lui. Chaque changement remet à zéro le compteur d’échecs, car le client va se faire communiquer un secret différent.

Lever un verrouillage

Cinq mauvaises réponses verrouillent l’invitation. Ceci lève le verrouillage ; passez rotate: true pour générer aussi un nouveau secret. La rotation est optionnelle car la cause habituelle est une faute de frappe, et un nouveau secret oblige simplement à le redicter.

{
  "rotate": true
}

Déverrouillage du client

La page invité échange la réponse contre un jeton de déverrouillage éphémère, ensuite exigé lors de la connexion de signalisation. Cinq réponses erronées verrouillent l'invitation et renvoient 403 avec code: "invitation_locked" jusqu'à ce qu'un agent la débloque.

Envoyez le code de l'invitation, son token (le fragment de l'URL d'invitation) et la réponse du client dans answer : le mot de passe, ou le code à 6 chiffres du moment. Omettez answer pour une invitation non protégée.

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

En cas de succès, vous recevez une preuve éphémère. Elle expire au bout de 60 minutes, ou avec l'invitation si celle-ci expire avant, et cesse d'être acceptée dès que le secret est renouvelé.

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

Réclamer l'invitation

La page invité appelle cet endpoint pour s'authentifier et faire sonner la session sur l'écran de l'agent. Une invitation protégée doit également présenter le jeton unlock obtenu à l'étape précédente.

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

Sans ce jeton — ou avec une preuve émise pour une autre invitation, ou contre un secret renouvelé entre-temps — l'appel est refusé avec 403 et code: "protection_required", sans rien changer à la session.

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

Émettre un jeton d'agent

Émet un nouveau jeton agent-view, valide 120 minutes, pour une session à laquelle l'appelant a déjà accès — utilisez-le pour réintégrer la visionneuse, par exemple après l'expiration de l’agentViewUrl d'origine. Accepte un label optionnel (1 à 64 caractères) affiché dans la liste des visionneuses du tableau de bord ; omis, un appelant clé API ou OAuth obtient "Integration viewer", un JWT de tableau de bord obtient "Dashboard viewer". Nécessite la permission view_sessions sur un JWT de tableau de bord, ou un jeton API/OAuth avec la portée 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..."
}

Résoudre une invitation (public)

Le point de terminaison public que la page invité appelle pour résoudre un code d'invitation en sa session et sa marque — aucun jeton ni clé requis. Rejoindre le flux s'authentifie séparément, avec le jeton intégré dans le fragment de l'URL d'invitation.

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