Open in
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 chat | Ce que votre bot appelle | Ce qui se passe |
|---|---|---|
| Envoyer « Appelez Comcast et obtenez l’heure estimée de rétablissement » | POST /v1/call avec le message comme context | L’agent compose le numéro. Votre bot ouvre un fil pour l’appel |
| Surveiller le fil | Reçoit des webhooks telephony.turn | Chaque ligne prononcée par l’agent ou l’autre personne apparaît dans le fil |
| Répondre dans le fil pendant l’appel | POST /v1/calls/{call_id}/whisper | L’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’agent | Votre endpoint d’outil renvoie votre réponse, ou la transmet plus tard avec POST /v1/calls/{call_id}/tool-results | L’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ésultat | Reçoit telephony.complete | Votre 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
contextde 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.turnettelephony.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 lesummaryde 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_idde l’enveloppe et triez parposition. 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
timeoutde 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.turnest 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.