---
title: "Connecter depuis Twilio"
description: "Envoyez des appels Twilio à un agent ThunderPhone via SIP avec le CallSid, puis récupérez-les via votre referUrl avec le transfert dans l’adresse de transfert."
---

Votre TwiML compose l’adresse SIP de l’agent avec le `CallSid` de l’appel dans un en-tête.
Lorsque l’appelant doit joindre une personne, l’agent envoie un `REFER` SIP, Twilio transmet l’adresse de transfert contenant le relais à votre gestionnaire `referUrl`, et le TwiML renvoyé par votre gestionnaire détermine où va l’appelant, par exemple vers une file Flex.

## Avant de commencer

- Un agent ThunderPhone et une [clé API](/fr/guides/api-keys) d’organisation.
- Twilio Programmable Voice, ainsi qu’un emplacement pour servir le TwiML et un
  gestionnaire `referUrl` : votre propre serveur, ou un TwiML Bin et une Twilio Function. Flex est
  facultatif.

## 1. Créez le point de terminaison SIP

Le composant `<Sip>` de Twilio accepte un nom d’utilisateur et un mot de passe, utilisez donc un point de terminaison standard :

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Twilio"}'
```

Enregistrez immédiatement le `password` de la réponse ; il n’est affiché qu’une seule fois. Pour
n’accepter que les appels provenant de Twilio, consultez
[Restreindre les IP sources](/fr/guides/sip-addresses).

## 2. Envoyez les appels avec du contexte

Renvoyez ce TwiML pour l’appel que vous souhaitez transmettre à l’agent :

```xml
<Response>
  <Dial answerOnBridge="true" referUrl="https://YOUR_SERVER/thunderphone-refer">
    <Sip username="tp409667538f83" password="YOUR_ENDPOINT_PASSWORD">sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls?X-Call-ID={{CallSid}}</Sip>
  </Dial>
</Response>
```

- `;transport=tls` est important : Twilio utilise UDP sauf indication contraire.
- `X-Call-ID` transmet le `CallSid`. Twilio ne documente pas d’en-tête d’identifiant d’appel
  natif, ajoutez donc celui-ci : ThunderPhone le stocke comme
  `external_call_id` de l’appel. `{{CallSid}}` fonctionne dans un TwiML Bin ; depuis votre propre serveur,
  écrivez le `CallSid` de la requête entrante.
- Ajoutez davantage de contexte de la même manière, par exemple `&amp;X-Account-Id=12345`. Dans
  TwiML, écrivez `&` sous la forme `&amp;`, car un `&` seul n’est pas un XML valide. Chaque valeur atteint le
  prompt sous forme de variable, ici `{{sip_x_account_id}}`. Twilio autorise les en-têtes `x-`
  et `User-to-User`, encodés en pourcentage, avec une URI entière de moins de 255 caractères
  et des en-têtes de moins de 1 024 caractères.
- `referUrl` permet à Twilio d’accepter le `REFER` de l’agent ; sans lui, le transfert
  échoue avec l’[erreur 13802](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` maintient l’appelant connecté jusqu’à ce que la nouvelle destination
  réponde, afin de prévoir une solution de repli en cas d’échec du transfert.

Le widget **Connecter l’appel à** de Studio ne documente pas les en-têtes personnalisés ni
`referUrl`. Depuis Studio, transmettez donc l’appel à ce TwiML, par exemple avec un
widget **Redirection TwiML**.

## 3. Récupérer l'appel

L'agent effectue le transfert avec un `REFER` dont l'adresse de transfert contient
l'identifiant et l'intention de passation. Ajoutez ce numéro de transfert (voir
[Ajouter le numéro de transfert](/fr/guides/contact-centers/overview)
et [En-têtes dans l'adresse de transfert](/fr/guides/call-transfers)) :

```json
{
  "name": "Twilio support",
  "number": "sip:support@acme.sip.twilio.com",
  "headers": {"X-Handoff-Id": "{{handoff_id}}", "X-Handoff-Intent": "{{handoff_intent}}"},
  "headers_in_uri": true
}
```

Twilio envoie l'adresse entière à votre `referUrl` sous la forme de `ReferTransferTarget`, par
exemple `<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>`.
Votre gestionnaire lit les en-têtes qu'elle contient et renvoie le TwiML correspondant à la prochaine
destination de l'appelant. La partie utilisateur de l'adresse (`support`) est à votre
choix. Vous pouvez donc ajouter un numéro de transfert par destination et effectuer le
routage en fonction de celui-ci.

Cette Function Twilio met l'appelant en file d'attente dans Flex avec la passation comme
attributs de tâche et recherche le résumé par identifiant de passation. La recherche s'exécute dans une
Function, car le widget HTTP Request de Studio ne peut pas envoyer l'en-tête
`Authorization` :

```js
exports.handler = async (context, event, callback) => {
  const target = (event.ReferTransferTarget || "").replace(/^<|>$/g, "");
  const params = new URLSearchParams(target.split("?")[1] || "");
  const handoffId = params.get("X-Handoff-Id") || "";
  const attributes = { handoff_id: handoffId, intent: params.get("X-Handoff-Intent") || "" };

  if (handoffId) {
    const response = await fetch(
      "https://api.thunderphone.com/v1/calls/handoff?handoff_id=" + encodeURIComponent(handoffId),
      { headers: { Authorization: "Bearer " + context.THUNDERPHONE_API_KEY } }
    );
    if (response.ok) {
      const call = await response.json();
      attributes.summary = (call.handoff && call.handoff.summary) || "";
    }
  }

  const twiml = new Twilio.twiml.VoiceResponse();
  twiml.enqueue({ workflowSid: context.FLEX_WORKFLOW_SID }).task({}, JSON.stringify(attributes));
  callback(null, twiml);
};
```

Conservez la clé API dans les variables d'environnement de la Function. Consultez
[Rechercher un appel transféré](/api-reference/calls#look-up-a-handed-off-call)
pour les autres champs.

## Tester

Appelez un numéro Twilio qui renvoie le TwiML ci-dessus, demandez à l'agent de parler à une personne,
puis vérifiez que votre gestionnaire `referUrl` reçoit `ReferTransferTarget` avec les deux
en-têtes et que l'appelant atteint la file d'attente. Ouvrez ensuite l'appel avec
`GET /v1/calls/{call_id}` : `external_call_id` doit correspondre au `CallSid`.

## Limites

- Twilio limite `Refer-To` à 256 caractères. ThunderPhone limite l'adresse à
  254 caractères et omet tout en-tête qui ne tient pas. Gardez donc les noms et valeurs
  d'en-tête courts.
- Twilio ne documente pas la lecture des en-têtes sur un `BYE`. Un retour ne peut donc pas
  retransmettre la passation à Twilio. Utilisez un `REFER` comme ci-dessus.
- Twilio n'accepte pas de `REFER` sur un appel connecté via `<Conference>` ou
  `<Queue>`. Composez donc le numéro de l'agent avec `<Dial><Sip>` comme ci-dessus.
