SIP et API OpenAI : connecter un agent IA au téléphone

Des cas d'usage qui justifient l'intégration

Les scénarios les plus robustes sont ceux où le téléphone est déjà un canal clé, et où une partie des demandes suit un chemin prévisible : qualification de l'appel, prise de rendez-vous, suivi d'une commande, ou orientation vers le bon service. Une entreprise peut aussi automatiser une première réponse en dehors des horaires d'ouverture, à condition de prévoir un transfert ou une solution de repli.

Dans un service client français, par exemple, l'agent peut recueillir le motif de l'appel et chercher une information dans un outil interne. Mais il ne doit pas prendre seul des décisions sensibles (modifier un dossier, communiquer des données personnelles) sans vérifier l'identité de l'appelant et les autorisations associées.

Ce que SIP ne résout pas

Relier un numéro ne garantit ni une conversation utile, ni un service conforme. Il faut aussi définir des consignes claires : règles d'accès, conditions d'escalade, gestion des interruptions, et comportement si le trunk tombe en échec. Le coût opérationnel dépendra aussi du volume, de la durée des appels, de l'infrastructure du fournisseur et de l'usage de l'API.

Le bon critère n'est donc pas « peut-on connecter l'IA au téléphone ? », mais « quelle étape de l'expérience client peut-on automatiser sans dégrader la résolution ? ». Suivez le taux de résolution, les transferts, les appels interrompus et les erreurs de compréhension avant d'étendre le dispositif.

Entrant ou sortant : deux parcours différents

Pour un appel entrant, le fournisseur route le trunk vers le projet OpenAI. Un webhook signale l'arrivée. Votre backend vérifie la requête, déduplique la livraison, puis accepte ou rejette. En cas d'acceptation, il transmet la configuration de session : modèle, consignes, voix et mode de délégation.

Pour un appel sortant, le backend crée une session en fournissant le numéro de destination et la configuration du trunk. Ici, pas de webhook d'appel entrant ni de requête d'acceptation. En revanche, la création de session ne prouve pas que la personne a décroché : il faut ensuite suivre les événements de progression de l'appel.

La connexion sideband et la responsabilité des événements

Après avoir accepté un appel entrant ou créé un appel sortant, votre backend peut se connecter à la session via WebSocket sideband. SIP transporte toujours l'audio. La sideband sert à superviser la conversation, recevoir des événements, gérer la délégation et envoyer des commandes.

Il y a un point d'architecture à ne pas rater : un même fait peut être observé sur plusieurs connexions, et un webhook peut être livré plusieurs fois. Attribuez un seul « propriétaire » à chaque effet de bord. Concrètement : un seul composant décide d'accepter l'appel, et un seul gestionnaire exécute l'action métier déclenchée par un événement. Sans cette règle, vous risquez des doublons : deux dossiers créés, deux SMS envoyés, ou deux transferts.

Un modèle de sécurité côté serveur

Pour contrôler l'appel et créer une session, vous avez besoin d'une authentification serveur avec une clé API. Gardez cette clé et les identifiants SIP dans un gestionnaire de secrets (ou dans l'environnement du serveur). Les en-têtes SIP (comme From ou Call-ID) sont des métadonnées fournies avec l'appel : elles ne sont pas une preuve d'identité.

Le mode de délégation doit aussi être choisi en connaissance de cause. Si vous activez une délégation de type client, votre backend doit gérer les opérations confiées. Ne sélectionnez pas un mode « par défaut » : décidez quel composant interprète les demandes, appelle les outils et gère les erreurs.

Vérifier et dédupliquer le webhook

À la réception de l'événement, vérifiez sa signature avec le corps brut et le secret de webhook, selon l'implémentation utilisée. Les en-têtes de livraison incluent notamment webhook-id, webhook-timestamp et webhook-signature. Utilisez l'identifiant de livraison pour éviter de retraiter le même webhook après une relance.

L'événement actuel identifie l'appel SIP avec data.type: "sip" et fournit data.session_id. Conservez cet identifiant sans le modifier pour les appels Live suivants. Les valeurs de data.sip_headers peuvent aider au diagnostic ou au routage, mais ce sont des données d'appel non fiables : ne vous en servez pas pour authentifier quoi que ce soit.

Accepter ou refuser avant de démarrer le dialogue

Avant de lancer la conversation, appliquez vos règles : numéro autorisé, plage horaire, capacité disponible, motif de rejet. Pour accepter, votre serveur envoie une requête POST /v1/live/sessions/{session_id}/accept avec un objet session qui contient les paramètres de conversation. Vous pouvez y définir le modèle, les instructions, la voix et le mode de délégation.

Côté audio, SIP négocie le format : ne renseignez pas audio.format dans cette configuration. Un 200 OK sans corps indique que l'initialisation de session a réussi ; si vous avez une erreur HTTP, traitez-la avant de considérer l'appel accepté. Pour refuser, utilisez POST /v1/live/sessions/{session_id}/reject avec un code SIP entier entre 300 et 699, par exemple 486 pour indiquer une ligne occupée. En cas de décisions concurrentes, la première décision prévaut.

Après l'acceptation, ouvrez la sideband avec l'identifiant de session accepté. Ne renvoyez pas une commande de démarrage de session. À ce stade, le backend peut superviser la conversation et appliquer ses règles de transfert ou de délégation.

Attention aux intégrations anciennes

Certaines intégrations existantes peuvent encore recevoir l'événement déprécié live.call.incoming, qui ne présente pas le même champ data.type. Pendant une migration, prévoyez le traitement des anciens événements et gardez l'abonnement nécessaire jusqu'à la fin des livraisons et relances historiques.

Surtout : évitez que deux API prennent la décision d'accepter un même appel « chacune de leur côté ». Centralisez cette responsabilité dans un seul gestionnaire, même si plusieurs flux d'événements vous remontent l'appel. C'est une règle d'idempotence, pas un détail.

Comprendre ce que dit (ou ne dit pas) la réponse

Si la création réussit, la réponse contient un identifiant de session et le type de transport SIP. Elle ne fournit ni SDP ni identifiants de trunk, et ne veut pas dire que l'appel a été répondu. Elle confirme uniquement l'initialisation de la session. Le fournisseur peut ensuite signaler sonnerie, réponse ou échec de mise en relation.

Connectez donc la sideband juste après la création. Elle peut rejouer les événements des trois secondes précédentes, mais si vous attendez trop, vous risquez de rater un événement de progression. Les événements rejoués gardent leur identifiant : dédupliquez-les via event_id pour ne pas traiter deux fois la même transition.

Suivre les événements et les limites d'appel

Les événements de transport donnent une vue opérationnelle du parcours : transport.ringing indique une sonnerie ou un média précoce, transport.answered signale que l'appel est établi, et transport.failed indique un échec après l'initialisation de session. Dans ce dernier cas, inspectez le code et le message d'erreur : une création peut réussir puis échouer sur le transport.

La sonnerie est limitée à trois minutes, et un appel connecté ne dépasse pas deux heures ; ces limites ne sont pas ajustables dans la requête de création. Votre application doit donc gérer une fin propre, les cas d'échec sans réponse, et la supervision des erreurs. Gardez la sideband ouverte jusqu'à la fermeture de session pour recevoir l'événement de clôture et les infos d'usage finales.

Contrôler un appel actif

Pour les appels entrants comme sortants, les commandes de contrôle permettent d'envoyer des tonalités DTMF, de transférer l'appel ou de raccrocher. Les événements DTMF reçus indiquent une touche pressée par l'appelant ; une tonalité envoyée depuis la sideband est confirmée par un événement de retour.

Pour transférer, utilisez POST /v1/live/sessions/{session_id}/refer avec un target_uri, qui peut être une destination tel: ou une URI SIP. Le fournisseur gère la suite du transfert. Pour terminer l'appel, utilisez POST /v1/live/sessions/{session_id}/hangup. Si vous avez besoin de récupérer l'usage final, gardez la connexion sideband ouverte jusqu'à la fermeture de session.

Construire un parcours compatible avec les obligations européennes

Si votre intégration gère des voix, des numéros ou des informations de dossier, vous devez l'évaluer au regard du RGPD et des règles applicables à votre activité. La conformité ne se résume pas au choix d'un endpoint européen. Définissez les finalités, les durées de conservation, les accès aux transcriptions éventuelles, et ce qui est dit à l'appelant. Faites relire le dispositif par vos équipes juridiques et sécurité, surtout si des données sensibles sont concernées.

Limitez les données transmises à l'agent à ce qui est nécessaire pour répondre. Si une vérification d'identité est requise, concevez-la explicitement : ne traitez pas la voix ou le numéro présenté comme une preuve « automatique ». Prévoyez aussi un transfert vers un humain en cas d'incertitude, de demande explicite, ou de situation hors du périmètre de l'agent.

Liste de contrôle avant mise en production

• Un seul gestionnaire décide d'accepter ou de refuser chaque appel.
• Les webhooks sont authentifiés et dédupliqués.
• Les clés API et secrets SIP restent côté serveur.
• Le trunk utilise TLS pour la signalisation et SRTP pour le média.
• Les événements d'appel sont suivis et dédupliqués par identifiant.
• Les scénarios d'échec, de transfert et de fin d'appel ont été testés.
• Les données collectées, leur conservation et l'information donnée à l'appelant sont documentées.