---
title: "Lancez des appels depuis Slack ou une application de chat"
description: "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`](/api-reference/outbound-calls) 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`](/fr/webhooks/events) | 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`](/api-reference/calls#whisper-to-the-agent) | 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](/fr/guides/build-tool-integration) renvoie votre réponse, ou la transmet plus tard avec [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | 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`](/fr/webhooks/events) | 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](/fr/guides/api-keys)).
- **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](/fr/webhooks/endpoints).
  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](https://api.slack.com/apps).

<Tip>
  Utilisez une application Slack que vous créez pour votre propre espace de travail, et recevez les messages
  via l’API Events de Slack plutôt que de lire l’historique des canaux. Slack
  impose des limites de lecture strictes aux applications distribuées vers d’autres espaces de travail hors de
  sa Marketplace ; une application que vous créez pour votre propre espace de travail n’y est pas soumise,
  et les événements vous parviennent au moment où ils se produisent, sans aucune lecture. Portées
  de bot courantes : `chat:write`, `app_mentions:read`, `im:history` (messages
  directs), `channels:history` et `groups:history` (réponses dans les fils des
  canaux publics et privés auxquels le bot participe). Abonnez-vous aux événements de bot
  `app_mention`, `message.im`, `message.channels` et `message.groups`, et
  activez l’onglet Messages sous Accueil de l’application afin que les personnes puissent envoyer des messages directs au bot.
</Tip>

## 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` :

```bash
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](/fr/guides/verify-webhook-signatures).
- **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](/fr/webhooks/call-complete) 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 :

```bash
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](/fr/guides/build-tool-integration) 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](/api-reference/integrations#timeout-and-wait-mode), 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 :

```json
{"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`](/api-reference/calls#deliver-a-tool-result) :

```bash
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](/fr/tools/overview).

**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 :

```text
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`](/api-reference/organizations#legacy-single-url-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](/fr/guides/outbound-calling-laws).

## Créez-le avec un agent de programmation

Indiquez à votre agent de programmation le [serveur MCP de la documentation](/fr/guides/docs-mcp) 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.
