--- title: "Connexion via SIP (sans numéro de téléphone)" description: "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-@sip.thunderphone.com` | `sip:agent--@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, éventuellement, une liste d’autorisation d’IP source) | | Recommandé pour | Les applications qui appellent déjà une API avant de transférer un appel ; les variables par appel | Les PBX et opérateurs qui doivent simplement « diriger 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 ```bash 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"} }' ``` ```json { "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](/fr/guides/call-variables). - `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 : ```xml sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp ``` 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 ```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": "Main PBX"}' ``` ```json { "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" } ``` Le `password` n'est renvoyé qu'une seule fois, lors de la création du point de terminaison. Enregistrez-le immédiatement dans la configuration de votre PBX ou de votre opérateur. Si vous le perdez, renouvelez-le avec `POST /v1/sip-endpoints/{id}/rotate-password`. ### 2. Configurez votre système pour l'utiliser Configurez un trunk SIP ou une destination avec : | Paramètre | Valeur | |---|---| | URI SIP | le `sip_uri` du point de terminaison | | Nom d'utilisateur / mot de passe | `username` / `password` (authentification Digest ; ThunderPhone interroge chaque appel) | | 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 | Privilégiez TCP ou TLS. UDP fonctionne depuis des adresses publiques et la plupart des NAT, mais derrière un NAT « symétrique » (qui utilise un nouveau port pour chaque destination), les raccrochages et transferts de l'agent vocal risquent de ne pas atteindre votre système. Une liste d'autorisation d'IP source (ci-dessous) nécessite également TCP ou TLS. Avec TLS, la signalisation SIP reste aussi chiffrée après `sip.thunderphone.com`, jusqu'aux serveurs qui traitent l'appel. 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 : ```bash 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. La liste d'autorisation n'est vérifiée que pour les appels via TCP ou TLS. Une adresse source UDP peut être falsifiée ; un point de terminaison doté d'une liste d'autorisation refuse donc tous les appels arrivant via UDP. Envoyez-lui les appels avec `;transport=tcp` (port 5060) ou via TLS (port 5061). ## 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 ``, 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](https://www.twilio.com/docs/voice/api/refer-to-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](/fr/guides/pricing). ## 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](/api-reference/sip-addresses).