Connexion via SIP (sans numéro de téléphone)

Envoyez des appels à un agent ThunderPhone directement depuis votre PBX, votre opérateur ou votre application SIP, avec un URI SIP à usage unique par appel ou une adresse SIP permanente.

Si votre propre système gère déjà les numéros de téléphone (un PBX, une plateforme de centre de contact ou un compte opérateur où vous alternez les numéros), vous pouvez envoyer des appels à un agent ThunderPhone via SIP standard. Vous n’importez ni n’achetez de numéro sur ThunderPhone. Votre système compose une adresse SIP et l’agent répond.

Il existe deux types d’adresse SIP :

Les deux types sont routés vers un agent de votre organisation et apparaissent tous deux dans l’historique des appels comme n’importe quel autre appel entrant.

URI SIP par appel#

1. Enregistrer l’appel#

curl -X POST https://api.thunderphone.com/v1/calls/register-sip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "to_number": "+14155550142",
    "variables": {"customer_name": "Ada"}
  }'

{
  "call_id": 862197007562,
  "sip_uri": "sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com",
  "expires_at": "2026-09-25T21:49:52Z",
  "agent_id": 12,
  "to_number": "+14155550142"
}

• to_number (facultatif) est le numéro que l’appelant a composé de votre côté. Il est enregistré comme destination de l’appel dans l’historique des appels, et l’agent le voit comme son propre numéro.
• variables (facultatif) renseignent les {{placeholders}} dans le prompt de l’agent, de la même manière que pour les appels sortants.
• call_id est l’identifiant que l’appel aura dans l’historique des appels (GET /v1/calls/{call_id}) une fois la connexion établie.

2. Composer l’URI#

Envoyez l’appel vers sip_uri dans les 5 minutes. L’URI ne fonctionne que pour un seul appel : une fois qu’un appel l’a utilisée, elle est consommée, même si cet appel se termine rapidement.

Avec Twilio, par exemple, renvoyez ce TwiML pour l’appel que vous souhaitez transférer :

<Response>
  <Dial>
    <Sip>sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp</Sip>
  </Dial>
</Response>

Depuis un PBX, composez l’URI comme destination SIP. Aucun nom d’utilisateur ni mot de passe n’est nécessaire ; le jeton constitue l’identifiant, traitez donc l’URI comme un mot de passe jusqu’à ce qu’elle ait été utilisée.

Point de terminaison SIP (adresse permanente)#

1. Créez le point de terminaison#

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": "Main PBX"}'

{
  "id": 7,
  "name": "Main PBX",
  "agent_id": 12,
  "sip_uri": "sip:agent-12-jhxmginwjx@sip.thunderphone.com",
  "username": "tp409667538f83",
  "password": "8mJ0…",
  "allowed_source_cidrs": [],
  "status": "active",
  "created_at": "2026-09-25T21:46:18Z"
}

2. Configurez votre système pour l'utiliser#

Configurez un trunk SIP ou une destination avec :

Ces paramètres de transport et de codec s'appliquent également aux URI par appel. Deux détails réseau sont importants pour les deux types d'adresse :

• Suivez Record-Route. Après le premier INVITE, le reste de la signalisation de l'appel (ACK, raccrochage, transferts) est envoyé au serveur ThunderPhone spécifique qui a répondu, indiqué dans l'en-tête Record-Route (sip-1.thunderphone.com ou sip-2.thunderphone.com, ou son adresse IP). Si vous restreignez les SIP sortants, autorisez ces hôtes ainsi que sip.thunderphone.com : 172.170.39.202 (sip), 13.86.104.121 (sip-1) et 20.80.98.90 (sip-2).
• L'audio passe ailleurs. sip.thunderphone.com ne transporte que la signalisation. Autorisez les médias (RTP) vers les adresses et ports indiqués dans la réponse SDP.

Chaque appel vers l'adresse atteint l'agent vocal du point de terminaison, quel que soit le numéro composé par votre appelant de votre côté. Vous n'importez jamais de numéros ; leur rotation de votre côté ne nécessite donc aucune modification dans ThunderPhone.

Transmettez le numéro composé (facultatif)#

Pour enregistrer lequel de vos numéros l'appelant a composé, envoyez-le dans l'INVITE via un en-tête X-Original-To (par exemple X-Original-To: +14155550142) ou un en-tête standard Diversion. ThunderPhone l'enregistre comme destination de l'appel.

La destination est sélectionnée dans cet ordre : le to_number fourni lors de l'enregistrement d'un URI par appel, puis un numéro dans X-Original-To, puis un numéro dans Diversion. Si aucun de ces éléments ne fournit de numéro, elle s'affiche comme sip:agent-12-jhxmginwjx (l'adresse du point de terminaison) pour un point de terminaison, ou comme sip:call pour un URI par appel.

Avec Twilio, vous pouvez ajouter l'en-tête à l'URI SIP : sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142.

Restreignez les IP sources (facultatif)#

Définissez allowed_source_cidrs afin de n'accepter que les appels provenant de vos propres adresses de signalisation, en plus du nom d'utilisateur et du mot de passe :

curl -X PATCH https://api.thunderphone.com/v1/sip-endpoints/7 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_source_cidrs": ["203.0.113.0/28"]}'

Les appels provenant de toute autre adresse sont refusés avant d'atteindre l'agent vocal. Utilisez les adresses depuis lesquelles votre système envoie la signalisation SIP (pour un opérateur tel que Twilio, ses plages d'IP de signalisation publiées), et non vos adresses média.

Ce que voient les appelants et votre système#

• Identifiant de l’appelant : la partie utilisateur de l’en-tête From est enregistrée comme appelant. Un numéro de téléphone (chiffres, éventuellement avec +, espaces, tirets, points ou parenthèses) est normalisé au format E.164 ; tout autre élément, tel qu’un nom d’utilisateur SIP, est conservé tel qu’envoyé. Au maximum 32 caractères sont conservés, et un appelant manquant est enregistré sous anonymous.
• Appels refusés : un URI par appel inconnu ou expiré reçoit SIP 404 Not Found. Un URI par appel déjà utilisé, un point de terminaison désactivé ou une source hors de la liste d’autorisation (y compris tout appel UDP vers un point de terminaison avec une liste d’autorisation) est déconnecté avant le démarrage de l’agent : votre système peut voir l’appel échouer, ou se connecter puis se terminer immédiatement. Ces refus ne créent pas d’entrée dans l’historique des appels. Si votre organisation n’a plus de crédit ou a atteint sa limite de dépenses, l’appel est refusé et apparaît dans l’historique des appels comme un appel échoué sans frais. Pour réessayer une tentative par appel, enregistrez un nouvel URI.
• Transferts : les transferts aveugles de l’agent fonctionnent (ThunderPhone envoie un SIP REFER, que votre système doit accepter). Les transferts assistés ne sont pas disponibles pour les appels vers une adresse SIP, car aucun numéro ThunderPhone ne peut s’afficher comme identifiant de l’appelant pour la deuxième partie de l’appel. Avec Twilio, le TwiML ci-dessus connecte l’agent mais ne gère pas les transferts : ajoutez referUrl="https://YOUR_SERVER/sip-transfer" au <Dial>, puis faites en sorte que ce webhook lise ReferTransferTarget et renvoie du TwiML qui compose la destination du transfert (consultez le guide SIP REFER de Twilio).
• Messages texte : l’adresse SIP et le numéro composé ne peuvent pas envoyer de messages texte. L’agent peut envoyer des messages texte lors d’un appel vers une adresse SIP uniquement s’il dispose d’un numéro distinct compatible SMS configuré pour les messages texte ; sinon, son outil SMS est indisponible.
• Enregistrement : ThunderPhone n’accepte pas SIP REGISTER. Envoyez les appels à l’adresse ; ne vous y enregistrez pas.

Tarification#

Les appels vers une adresse SIP sont facturés au tarif normal de l’agent par minute. Il n’y a pas de frais de numéro de téléphone, car aucun numéro ThunderPhone ne prend en charge l’appel. Votre propre opérateur facture sa partie de l’appel comme d’habitude. Consultez la tarification.

Tester#

1. Créez un URI par appel ou un point de terminaison comme indiqué ci-dessus.
2. Composez-le depuis votre système ou depuis n’importe quel softphone SIP (pour un point de terminaison, saisissez le nom d’utilisateur et le mot de passe).
3. Après avoir raccroché, ouvrez l’appel dans Appels du tableau de bord, ou récupérez-le avec GET /v1/calls/{call_id}. Il affiche l’appelant, la destination (voir l’ordre sous « Transmettre le numéro composé ») et la transcription.

Détails de l’API : référence de l’API des adresses SIP.