Préproduction : l'API répond sur https://api.visiobank.com/v1, avec une clé de test. Les exemples gardent l'adresse de production, api.vizalia.ai, qui ouvrira à la mise en production.

Sessions

Une session est un appel visuel avec un client, du lien envoyé à la fin de l’appel. Votre logiciel la crée, la suit par ses événements et la termine.

Les statuts

pending créée, invitation pas encore partie ou lien seul ; invited invitation acceptée par l'opérateur ; invitation_failed envoi en échec ; opened lien ouvert par le client ; live vidéo établie ; ended session terminée.

Créer une session

POST /sessions envoie l’invitation par SMS (channel: sms, to au format E.164) ou par e-mail (channel: email). Avec channel: link, rien ne part : la réponse donne le lien du client, join_url, à transmettre par votre propre canal.

Donnez toujours channel. Sans lui, l’API attend un numéro dans to, et répond 422 phone_required s’il manque. Avec channel: link, n’envoyez pas to : la requête est refusée (400 invalid_request).

Un même destinataire relancé dans l’heure rouvre sa session, même terminée, au lieu d’en créer une autre : la réponse est 200 avec reopened: true, au lieu de 201. La session reprend avec son statut et ses médias ; reference et metadata prennent les valeurs de la nouvelle demande. C’est voulu : un client rappelé dans l’heure retrouve son appel.

Le lien du client

join_url donne accès à la session : traitez-le comme un secret, et ne le journalisez pas. Il cesse de fonctionner à expires_at, dont la durée dépend des réglages de l’espace : lisez-la plutôt que de la supposer. POST /sessions/{session_id}/resend renvoie l’invitation d’une session non terminée ; il compte dans les plafonds d’envoi. Il ne change pas de destinataire : pour un autre numéro, créez une autre session. En mode test, il répond sans rien renvoyer ; avec channel: link, il n’y a pas d’invitation à renvoyer, et il répond 422 phone_required.

Ouvrir le poste conseiller

advisor_url ouvre le poste conseiller de la session, depuis votre outil, sans compte Vizalia pour le conseiller : le lien porte un jeton propre à cet appel, à durée limitée.

Le poste s’ouvre dans un onglet ou dans un cadre de votre page :

<iframe
  src="ADVISOR_URL"
  allow="camera; microphone; display-capture; autoplay"
  style="width: 100%; height: 100%; border: 0"
></iframe>

allow est indispensable : sans lui, le navigateur refuse la caméra et le micro dans un cadre d’une autre origine.
Les domaines qui embarquent le poste sont déclarés à Vizalia, en préproduction comme en production : sans cela, le poste refuse de s’afficher dans votre cadre.
Si votre page applique une CSP, autorisez l’origine de advisor_url dans frame-src.

À la fin de l’appel, le cadre prévient votre page par un message. Contrôlez toujours son origine :

const origineDuPoste = new URL(advisorUrl).origin;

window.addEventListener('message', (evenement) => {
  if (evenement.origin === origineDuPoste && evenement.data?.type === 'uploadCompleted') {
    // L'appel est terminé : fermez le cadre, rafraîchissez le dossier.
  }
});

Côté serveur, le signal de fin est le webhook session.ended.

Terminer une session

POST /sessions/{session_id}/end termine la session et arrête les enregistrements en cours. L’appel est rejouable : terminer une session déjà terminée la renvoie sans erreur. Le summary éventuel est versé au rapport ; un second end le remplace. Pour annuler une session dont le lien n’a pas été ouvert, terminez-la de la même façon.

duration_seconds est la durée de coprésence du client et du conseiller (ou de l’agent) : elle reste nulle tant qu’aucune coprésence n’a été mesurée, par exemple après une session simulée.

Retrouver une session

GET /sessions liste les sessions de l’espace, les plus récentes d’abord, avec ces filtres :

Filtre	Correspondance
`reference`	Votre référence, exacte.
`metadata[clé]=valeur`	Une donnée libre, exacte, une seule clé par requête.
`to`	Le destinataire exact. Encodez le `+` d’un numéro : `to=%2B33612345678`.
`status`	Un statut.
`created_after`, `created_before`	La date de création ; `created_after` est inclusif.

Une valeur de filtre que l’API ne connaît pas, comme un statut qui n’existe pas ou deux clés metadata dans la même requête, répond 400 invalid_request. La liste se parcourt par pagination.