ThunderPhone v3 est disponible.En libre-service, à partir de 2 ¢/min.Découvrir l’annonce

Developer cookbook

Lancez des appels depuis Slack ou une application de chat

Créez votre propre bot Slack, Teams ou de chat web qui lance des appels, les suit en direct, guide l’agent et répond à ses questions, à l’aide de l’API publique.

Vous pouvez piloter un agent depuis l’application de chat que votre équipe utilise déjà. Un message démarre un appel. L’appel se déroule en direct dans un fil. Une réponse dans le fil oriente l’agent. Lorsque l’agent a besoin d’une décision, il vous la demande dans ce fil et attend votre réponse.

ThunderPhone n’héberge pas ce bot pour vous. Vous (ou votre agent de programmation) créez un petit serveur qui connecte votre application de chat à l’API publique. Cette page présente les éléments nécessaires. Ils sont les mêmes pour Slack, Microsoft Teams, Discord ou une page de chat web privée ; les exemples utilisent Slack.

Fonctionnement

Ce que vous faites dans le chatCe que votre bot appelleCe qui se passe
Envoyer « Appelez Comcast et obtenez l’heure estimée de rétablissement »POST /v1/call avec le message comme contextL’agent compose le numéro. Votre bot ouvre un fil pour l’appel
Surveiller le filReçoit des webhooks telephony.turnChaque ligne prononcée par l’agent ou l’autre personne apparaît dans le fil
Répondre dans le fil pendant l’appelPOST /v1/calls/{call_id}/whisperL’agent reçoit votre note en privé et agit en conséquence. L’autre personne ne l’entend jamais
Répondre à la question de l’agentVotre endpoint d’outil renvoie votre réponse, ou la transmet plus tard avec POST /v1/calls/{call_id}/tool-resultsL’agent poursuit l’appel avec cette réponse ; en mode attente, l’autre personne entend de la musique d’attente pendant ce temps
Lire le résultatReçoit telephony.completeVotre bot publie le résumé et le résultat

Votre bot conserve un seul mappage : quel fil de chat appartient à quel call_id.

Avant de commencer

  • Une clé API, conservée sur votre serveur et jamais dans un navigateur ou un chat. Créez-en une dans Intégrations → Clés API (voir Créer une clé API serveur).
  • Un numéro activé pour les appels sortants et un agent pour les appels. Le message devient le context de chaque appel, afin qu'un agent général puisse gérer toutes les tâches.
  • Un serveur capable de recevoir des webhooks, tel que Railway, Fly.io, Render ou votre propre hébergement.
  • Un endpoint de webhook pointant vers ce serveur et abonné à telephony.turn et telephony.complete. Les événements de tour sont envoyés uniquement aux endpoints qui les répertorient. Voir Webhooks. Les événements de tour nécessitent que l'enregistrement des appels de l'agent soit activé, et le summary de fin d'appel nécessite le paramètre Générer un résumé d'appel de l'agent ; sans cela, ces champs restent vides.
  • Votre propre application de chat. Pour Slack, créez une application dans votre espace de travail sur api.slack.com/apps.

1. Démarrer un appel depuis un message

Lorsque votre bot reçoit un message (un message direct ou une @mention), accusez immédiatement réception de la demande de Slack (Slack réessaie tout élément non acquitté dans les 3 secondes) et effectuez le reste en arrière-plan. Vérifiez que l’expéditeur est autorisé à passer des appels, puis démarrez l’appel avec le message comme context :

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'

Enregistrez le call_id renvoyé avec le fil Slack (channel plus le ts du message) et répondez dans le fil (« Appel en cours… »). Construisez la idempotency_key à partir du canal et du ts du message (un ts est unique uniquement dans son canal), afin qu’un événement Slack réessayé ne lance pas un second appel. Si la demande mentionne une personne plutôt qu’un numéro, votre bot recherche d’abord le numéro. ThunderPhone compose uniquement le to_number que vous envoyez.

2. Suivre l’appel dans le fil

Chaque webhook telephony.turn contient le call_id, le locuteur (role : assistant pour l’agent, user pour l’autre personne), le text et la position du tour. Recherchez le fil à l’aide du call_id et publiez la ligne.

  • Vérifiez chaque webhook avant d’agir. Consultez Vérifier les signatures des webhooks.
  • Dédupliquez selon le event_id de l’enveloppe et triez par position. La livraison est effectuée au moins une fois, et les tours peuvent arriver dans le désordre.
  • Regroupez les lignes si un appel chargé risque d’inonder le fil ; publier toutes les quelques secondes est plus lisible qu’un message par ligne.

Lorsque telephony.complete arrive, publiez la façon dont l’appel s’est terminé (son status et son end_reason), le summary et toutes les données extraites, puis clôturez le fil. Consultez Fin d’appel pour connaître les champs.

3. Guider l’appel depuis le fil

Lorsqu’une personne répond dans le fil d’un appel en cours, envoyez la réponse comme un chuchotement, sauf si l’agent attend la réponse à une question (étape 4), auquel cas la réponse est la réponse attendue :

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'

L’agent l’entend en privé et l’intègre à son prochain tour ; l’autre personne n’entend jamais le chuchotement lui-même. Un chuchotement contient de 1 à 1 000 caractères. Un 409 signifie que l’appel n’est plus en cours : indiquez au fil que l’appel est terminé.

4. Laissez l'agent vous poser une question

Donnez à l'agent un outil, par exemple ask_owner, avec un paramètre question, qui appelle votre serveur. Créez-le comme une connexion API et associez-le à l'agent. Chaque requête d'outil contient l'appel dans son en-tête X-ThunderPhone-Call-ID.

Il existe trois façons de récupérer la réponse.

Mettre l'appel en attente (jusqu'à 10 minutes). Configurez l'outil en mode de mise en attente : spec.wait_mode "hold" et spec.timeout jusqu'à 600 secondes (sans délai d'expiration, une mise en attente dure 20 secondes), via l' API, ou demandez à Zeus de les configurer (les éditeurs de l'application ne disposent encore d'aucun de ces champs). Votre point de terminaison publie la question dans le fil de discussion de l'appel et répond immédiatement avec un résultat en attente :

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

L'autre personne entend une phrase de l'agent, puis de la musique d'attente. Dans un menu téléphonique ou une messagerie vocale, l'agent utilise plutôt des mises à jour orales, et un agent full-duplex ne met pas l'appel en attente : il reçoit la réponse en attente comme résultat. Lorsque la réponse arrive dans le fil, transmettez-la avec POST /v1/calls/{call_id}/tool-results :

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'

La musique s'estompe et l'agent poursuit avec votre réponse. Si personne ne répond avant le timeout, l'agent est informé qu'aucune réponse n'est arrivée et propose les prochaines étapes à l'autre personne. Tant qu'une question est en attente pour un appel, la réponse suivante dans son fil y répond : transmettez-la comme résultat de l'outil et ne l'envoyez pas aussi comme chuchotement (un chuchotement n'atteint l'agent qu'après le retour de l'outil). Consultez Attentes longues.

Attendez dans la requête (jusqu'à 3 minutes). Votre endpoint publie la question, attend une réponse et la renvoie, par exemple {"answer": "Yes, book Tuesday at 10."}. Configurez le spec.timeout de l'outil via l'API, jusqu'à 180 secondes (la valeur par défaut est 20). Donnez à votre endpoint son propre délai d'expiration quelques secondes plus court (par exemple 170 secondes), afin que lorsqu'aucune personne ne répond, il renvoie tout de même quelque chose sur quoi l'agent peut agir, par exemple {"answer": null, "note": "No reply yet. Offer to take a message."}. Un outil qui atteint son timeout arrive à l'agent comme une erreur, et votre hôte doit maintenir une requête ouverte aussi longtemps. Pendant qu'il attend, l'agent dit à l'autre personne qu'il vérifie, indique qu'il travaille encore après environ 12 secondes, puis donne une courte mise à jour environ toutes les 15 secondes. Le mode attente fonctionne aussi ici : définissez spec.wait_mode sur "hold" et l'autre personne entend de la musique au lieu des mises à jour.

Répondez par chuchotement. Votre endpoint publie la question et renvoie immédiatement, par exemple {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Lorsque la réponse arrive, envoyez-la comme chuchotement (étape 3), et l'agent y répond immédiatement. Utilisez cette méthode pour les réponses qui peuvent prendre plus de 10 minutes. L'appel n'est pas mis en attente : votre prompt doit indiquer à l' agent quoi faire entre-temps, par exemple tenir compagnie à la personne ou proposer de la rappeler.

Dans tous les cas, indiquez dans le prompt de l'agent quand utiliser l'outil et quoi dire à l'autre personne pendant qu'il attend :

When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.

Limites à anticiper

  • Votre endpoint doit répondre dans le délai timeout de l'outil, soit 180 secondes au maximum. Un outil en mode d'attente peut mettre l'appel en attente pendant 600 secondes au maximum avec un résultat en attente.
  • Pendant qu'un outil attend, l'agent ne répond pas à l'autre personne. En mode d'attente, elle entend de la musique ; sinon, de courts messages vocaux.
  • Un chuchotement contient au maximum 1000 caractères.
  • La remise de telephony.turn est effectuée au moins une fois et peut ne pas respecter l'ordre.

Liste de contrôle de sécurité

  • Conservez la clé API sur votre serveur.
  • Vérifiez les signatures de ThunderPhone sur les webhooks et les requêtes d'outil, ainsi que le secret de signature de Slack sur les requêtes Slack. Les deux signatures ThunderPhone utilisent des secrets différents : les livraisons de webhook utilisent le secret propre à l'endpoint webhook, tandis que les requêtes d'outil utilisent le secret webhook de votre organisation provenant de GET /v1/webhook.
  • Décidez qui peut démarrer des appels : vérifiez l'ID utilisateur Slack avant d'en passer un.
  • Les appels sortants suivent les mêmes règles que tous les autres. Consultez Lois sur les appels sortants.

Créez-le avec un agent de programmation

Indiquez à votre agent de programmation le serveur MCP de la documentation et cette page, puis demandez-lui « un bot Slack pour mon agent ThunderPhone qui suit ce guide ». Zeus, l'assistant de l'application ThunderPhone, peut configurer la partie agent (l'endpoint webhook, l'outil et les lignes du prompt) et écrire le code de démarrage du bot dans le chat.