Open in
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 :
| URI SIP par appel | Point de terminaison SIP | |
|---|---|---|
| Se présente comme | sip:c-<token>@sip.thunderphone.com | sip:agent-<id>-<letters>@sip.thunderphone.com |
| Créé avec | POST /v1/calls/register-sip, une fois par appel | POST /v1/sip-endpoints, une fois |
| Authentification | Le jeton à usage unique dans l’adresse | Nom d’utilisateur et mot de passe SIP digest (et, facultativement, une liste d’autorisation d’IP source), ou une liste d’autorisation d’IP source seule pour les plateformes qui s’authentifient par IP |
| Adapté à | Applications qui appellent déjà une API avant de transférer un appel ; variables par appel | PBX et opérateurs qui doivent simplement « pointer un trunk » vers ThunderPhone |
| Valide pendant | 5 minutes, un appel | Jusqu’à sa suppression |
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_idest 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",
"auth": "digest",
"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 :
| Paramètre | Valeur |
|---|---|
| URI SIP | l’sip_uri du point de terminaison |
| Nom d’utilisateur / mot de passe | username / password (authentification Digest ; ThunderPhone authentifie chaque appel). Aucun pour un point de terminaison ip_allowlist (ci-dessous) |
| Transport | TCP sur le port 5060 ou TLS sur le port 5061 (recommandé), ou UDP sur le port 5060 |
| Codecs | G.711 (PCMU/PCMA) ou G.722 |
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.comousip-2.thunderphone.com, ou son adresse IP). Si vous restreignez les SIP sortants, autorisez ces hôtes ainsi quesip.thunderphone.com:172.170.39.202(sip),13.86.104.121(sip-1) et20.80.98.90(sip-2). - L'audio passe ailleurs.
sip.thunderphone.comne 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.
Plateformes qui s'authentifient par adresse IP source
Certaines plateformes de centre de contact, telles que Talkdesk, Amazon Connect et Amazon
Chime Voice Connector, s'identifient uniquement par les adresses
depuis lesquelles elles envoient du SIP et ne documentent aucune authentification par mot de passe. Pour celles-ci, créez
le point de terminaison avec auth défini sur ip_allowlist et listez les plages de signalisation SIP de la plateforme :
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": "Amazon Chime",
"auth": "ip_allowlist",
"allowed_source_cidrs": ["3.80.16.0/23", "99.77.253.0/24"]
}'La réponse contient "username": null et aucun password. Configurez la plateforme pour utiliser
le sip_uri via TLS (port 5061) ou TCP (port 5060) : un point de terminaison ip_allowlist
refuse tous les appels via UDP, car une adresse source UDP peut être
usurpée.
La liste doit contenir au moins une entrée. Chaque entrée doit être une plage IPv4 publique de
/16 ou plus restreinte, ou une plage IPv6 de /48 ou plus restreinte. Utilisez les plages de signalisation
publiées par la plateforme pour les régions que vous utilisez, et non ses plages média
ni celles de l'ensemble d'un fournisseur cloud.
Pour modifier un point de terminaison existant, envoyez-lui un PATCH avec auth (et
allowed_source_cidrs si sa liste ne respecte pas ces règles). Revenir à
digest renvoie une fois un nouveau mot de passe.
Plateformes qui composent un numéro de téléphone
Five9, NICE CXone et Zoom Contact Center envoient un appel vers un numéro de téléphone et
ne peuvent pas composer l’adresse agent-… du point de terminaison. Attribuez jusqu’à 5
dial_in_numbers à un point de terminaison ip_allowlist : la plateforme envoie alors son INVITE vers
sip:<number>@sip.thunderphone.com et atteint l’agent du point de terminaison. Zoom
Contact Center requiert également TLS avec SRTP ; définissez donc srtp sur required (SRTP,
comme les numéros d’appel entrant, est disponible uniquement sur les points de terminaison ip_allowlist) :
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": "Zoom Contact Center",
"auth": "ip_allowlist",
"allowed_source_cidrs": ["203.0.113.0/24", "198.51.100.0/24"],
"dial_in_numbers": ["999123456789012"],
"srtp": "required"
}'Remplacez les plages d’exemple (des adresses de documentation refusées par l’API)
par les plages de signalisation SIP de votre plateforme. Saisissez chaque numéro exactement tel que la
plateforme le compose, avec ou sans le +
(les numéros 999… à 15 chiffres de Zoom n’en ont pas) ; les espaces, tirets et parenthèses sont
supprimés. Un numéro est considéré comme une adresse, et non comme un mot de passe : les appels vers celui-ci sont
vérifiés par rapport à allowed_source_cidrs et doivent arriver via TCP ou TLS, comme
les appels vers sip_uri. Un numéro ne peut pas déjà être utilisé sur
ThunderPhone, comme numéro de téléphone ou sur un autre point de terminaison SIP ; toute création ou
mise à jour qui l’utilise renvoie 409. Pour modifier la liste, effectuez un PATCH sur le point de terminaison avec
l’ensemble des nouveaux dial_in_numbers.
Les appels vers un numéro d’appel entrant sont des appels à une adresse SIP : aucun numéro ThunderPhone
ne les transporte ; ils n’apparaissent donc pas dans les numéros de téléphone et ne génèrent aucun
frais de numéro de téléphone. La destination de l’appel est le numéro dans X-Original-To
ou Diversion lorsque la plateforme en envoie un, sinon le numéro d’appel entrant.
Transmettre le contexte d'appel dans les en-têtes SIP
Une plateforme de centre de contact ou un PBX connaît généralement des informations sur l'appel avant qu'il n'atteigne l'agent : son propre identifiant d'appel ou de contact, ce que l'appelant a choisi dans le SVI, le numéro de compte qu'il a saisi. Envoyez-les comme en-têtes SIP dans l'INVITE afin que l'agent puisse les utiliser.
ThunderPhone lit deux types d'en-têtes :
- chaque en-tête dont le nom commence par
X-(par exempleX-Amzn-ConnectContactIdouX-Intent), à l'exception deX-TP-*etX-LK-*, que les propres serveurs SIP de ThunderPhone utilisent et qui sont toujours supprimés ; User-to-User(UUI). Une valeur marquée;encoding=hexest décodée en texte lorsqu'elle se décode en UTF-8 ; la valeur telle qu'elle a été envoyée est également conservée.
Cela fonctionne avec les deux types d'adresse SIP et avec les numéros importés via une connexion SIP manuelle. Cela ne s'applique pas aux numéros ThunderPhone ni aux numéros sur une connexion Twilio ou Telnyx.
Les utiliser dans le prompt
Chaque en-tête devient une variable d'appel nommée sip_
suivie du nom de l'en-tête en minuscules, chaque suite de caractères autres que des
lettres et des chiffres étant remplacée par un seul _ :
| En-tête | Variable |
|---|---|
X-Amzn-ConnectContactId | {{sip_x_amzn_connectcontactid}} |
X-Intent | {{sip_x_intent}} |
User-to-User | {{sip_uui}} (décodé) et {{sip_uui_raw}} (tel qu'envoyé, uniquement lorsqu'il était encodé en hexadécimal) |
Un en-tête n'atteint l'agent que lorsque son prompt le nomme ; rien n'est ajouté
à la conversation autrement. Une variable du même nom provenant de
register-sip ou de votre webhook de configuration d'appel
est prioritaire sur l'en-tête. Donnez à chaque espace réservé une valeur par défaut
({{sip_x_intent|unknown}}) afin que les appels sans cet en-tête restent lisibles.
Limites
Au maximum 32 en-têtes par appel, 1 024 caractères par valeur et 8 Ko au total ; les en-têtes dépassant ces limites sont supprimés. Les caractères de contrôle sont supprimés.
Où ils apparaissent
- Historique des appels :
GET /v1/calls/{call_id}renvoiesip_headers(nom d’en-tête en minuscules → valeur), ounullpour un appel qui n’en contient aucun. - ID d’appel de votre plateforme : le premier de ces en-têtes transportés par l’appel est enregistré comme
external_call_idde l’appel :X-Amzn-ConnectContactId(Amazon Connect),x-inin-cnv(Genesys Cloud, avec le paramètre Conversation Headers du trunk activé),X-Talkdesk-Interaction-Id(Talkdesk),X-ZOOM-Call-Sid(Zoom Contact Center),X-CallID(Five9),X-Call-ID(définissez-le vous-même sur toute autre plateforme) etX-Genesys-Conversation-Id. Lorsque l’agent renvoie l’appel à votre plateforme,GET /v1/calls/handoffretrouve l’appel grâce à cet ID. - Webhooks : l’événement
telephony.incominginclutsip_headerslorsque l’appel en contient. Pour les numéros sur une connexion SIP manuelle, la requête de configuration d’appel bloquante et le webhook de configuration d’appel de l’agent les incluent également.
Ce que voient les appelants et votre système
- Identifiant de l'appelant : la partie utilisateur de l'en-tête
Fromest 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'il a été envoyé. Un maximum de 32 caractères est conservé, et un appelant absent est enregistré commeanonymous. - 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 constater l'échec de l'appel, ou la connexion puis la fin immédiate de l'appel. 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 à froid de l'agent fonctionnent (ThunderPhone envoie un SIP
REFER, que votre système doit accepter). Un numéro de transfert peut également être une adresse SIP dans votre système, telle qu'une file d'attente, avec des en-têtes SIP qu'elle peut lire ; consultez Transférer vers une adresse SIP. L'agent peut également renvoyer l'appel en raccrochant avec des en-têtes de routage sur leBYE; consultez Renvoyer l'appel vers votre centre de contact. 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 seconde étape. Avec Twilio, le TwiML ci-dessus connecte l'agent mais ne gère pas les transferts : ajoutezreferUrl="https://YOUR_SERVER/sip-transfer"à<Dial>, puis demandez à ce webhook de lireReferTransferTargetet de renvoyer un 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 SMS. L'agent peut envoyer des SMS pendant un appel vers une adresse SIP uniquement s'il dispose d'un numéro distinct compatible SMS configuré pour l'envoi de SMS ; sinon, son outil SMS est indisponible.
- Enregistrement : ThunderPhone n'accepte pas SIP
REGISTER. Envoyez les appels vers l'adresse ; ne vous y enregistrez pas.
Tarification
Les appels vers une adresse SIP sont facturés comme n’importe quel autre appel. Il n’y a pas de partie liée à la ligne téléphonique, car aucun numéro ThunderPhone ne transporte l’appel. Votre propre opérateur facture sa part de l’appel comme d’habitude. Consultez Tarification.
Tester
- Créez un URI par appel ou un endpoint comme ci-dessus.
- Composez-le depuis votre système ou depuis n’importe quel softphone SIP (pour un endpoint
digest, saisissez le nom d’utilisateur et le mot de passe ; un endpointip_allowlistrépond uniquement aux appels provenant de ses plages autorisées). - Après avoir raccroché, ouvrez l’appel dans Appels du dashboard, 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.