Utilisez vos propres numéros (VoIP, API)

Connectez Twilio, Telnyx, SignalWire, Vonage, Plivo ou tout autre trunk SIP via SIP, importez les numéros de téléphone que vous possédez déjà et laissez les agents ThunderPhone répondre aux appels et en passer avec ces numéros.

Les numéros ThunderPhone approuvés peuvent émettre des appels sortants et exécuter des campagnes. Si vous préférez utiliser vos propres numéros via votre propre fournisseur VoIP, ce guide vous accompagne dans le flux de connexion : tester les identifiants → créer la connexion → importer les numéros → vérifier.

Fournisseurs pris en charge#

1. Tester les identifiants#

Avant de créer une connexion VoIP persistante, testez les identifiants du fournisseur pour confirmer qu’ils fonctionnent. Cette opération renvoie un verification_evidence_id à transmettre à l’étape de création afin que les identifiants ne soient pas facturés deux fois pour les tests.

curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'

{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}

Si une vérification échoue, le status de la réponse sera fail et checks indiquera l’étape ayant échoué. Corrigez la configuration côté fournisseur (affectation du trunk, liste d’autorisation IP, autorisation des appels sortants), puis réessayez.

2. Créez la connexion#

Transmettez le verification_evidence_id que vous venez d’obtenir :

curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "Acme Telnyx Main",
    "provider":     "telnyx",
    "setup_method": "api_key",
    "credentials":  { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":   { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'

La réponse est un objet VoipConnection avec status="connected". Les identifiants et autres valeurs secrètes de connexion sont stockés côté serveur et ne sont jamais renvoyés en texte brut par les GET suivants — pour les renouveler, exécutez un nouveau test et effectuez un PATCH avec les nouvelles preuves.

Sous-comptes Twilio#

Une connexion Twilio est liée au compte Twilio unique dont elle contient l’Account SID et l’Auth Token. Twilio conserve les numéros de téléphone et les trunks SIP dans chaque sous-compte. Une connexion établie avec le compte parent ne voit donc que les propres numéros du parent, et une connexion existante ne peut pas être basculée vers un autre sous-compte ultérieurement.

Pour accéder aux numéros détenus dans des sous-comptes, créez une connexion par sous-compte. Le tableau de bord le fait pour vous : lorsque vous connectez un compte parent qui possède des sous-comptes actifs, la boîte de dialogue de configuration les liste, vous cochez ceux que vous souhaitez utiliser, et ThunderPhone crée une connexion (et un trunk SIP) dans chacun d’eux. Le même flux est disponible via l’API :

# Discover active subaccounts visible to the parent credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}'

{
  "discovery_id": "7c1e...",
  "parent": { "sid": "ACparent...", "friendly_name": "Acme" },
  "subaccounts": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "already_connected": true,  "connection_id": 5 }
  ]
}

# Create a connection for each selected subaccount
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}'

La réponse contient une ligne par sous-compte, avec un status de created, skipped (déjà connecté) ou failed, ainsi qu’une error sur laquelle vous pouvez agir. Les lignes sont indépendantes : un échec dans un sous-compte ne bloque jamais les autres, et un discovery_id reste valide pendant 30 minutes afin qu’une ligne en échec puisse simplement être relancée. Les jetons des sous-comptes sont lus depuis Twilio au moment de la découverte et stockés dans la nouvelle connexion ; ils ne sont jamais renvoyés par l’API. Chaque nouvelle connexion importe ensuite et vérifie les numéros exactement comme une connexion créée manuellement. Ajoutez "enable_transfers": true pour activer également les transferts d’appels sur le trunk SIP de chaque nouvelle connexion ; un échec à cette étape est signalé dans le champ test_result.transfer_enable_error de cette connexion et ne fait pas échouer la ligne.

3. Listez et importez des numéros#

Inspectez les numéros visibles avec vos identifiants qui ne figurent pas déjà dans une organisation ThunderPhone :

curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Importez ensuite ceux que vous souhaitez utiliser :

curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'

Chaque importation devient une ressource de numéro de téléphone dans votre organisation avec number_type="voip" et status="provisioning".

4. Vérifier chaque numéro importé#

L’importation enregistre le numéro comme disponible ; le routage effectif des appels via ce numéro nécessite une vérification. Pour les connexions à un fournisseur (Twilio, Telnyx), celle-ci vérifie à nouveau les identifiants du fournisseur et l’accessibilité SIP. Pour une connexion SIP manuelle, elle essaie d’abord un auto-appel en boucle : ThunderPhone effectue un court appel de test depuis le numéro, via votre trunk SIP, vers ce même numéro. Si cela ne permet pas de vérifier le chemin entrant, elle utilise un court appel de test depuis le numéro, via votre trunk SIP, vers un numéro ThunderPhone. Ces tests vérifient le nom d’utilisateur, le mot de passe, le transport, le routage sortant et la livraison entrante du trunk. Votre opérateur facture ces appels comme tous les autres.

curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

En cas de réussite, voip_verification_status passe à verified et le numéro passe à status="active". Un numéro de votre propre compte Telnyx continue de recevoir des appels entrants lorsque son appel de test échoue ou que les appels sortants ne sont pas encore configurés : il passe à status="active" avec voip_verification_status défini sur unverified, et la réponse en indique la raison. En cas d’échec, la réponse détaille ce qui a échoué — pour un trunk manuel, il s’agit de la réponse SIP de l’opérateur, par exemple « identifiants ThunderPhone refusés (SIP 401) » ou « impossible d’acheminer un appel (SIP 404) » — corrigez le problème (identifiants, adresses IP source autorisées, affectation de trunk manquante dans le tableau de bord du fournisseur), puis relancez l’appel.

Pour une connexion SIP manuelle autorisée par liste blanche, le test d’appel entrant échoue également si ces IP sources autorisées bloqueraient un véritable appel entrant.

5. Affecter des agents et recevoir un appel#

Une fois le numéro vérifié, affectez des agents entrants / sortants de la même manière que pour un numéro ThunderPhone. Consultez Traiter les appels entrants et Passer des appels sortants.

Rotation des identifiants#

Lorsqu’une clé fournisseur est renouvelée, exécutez à nouveau le flux de test puis de mise à jour :

# 1. Test the new credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/test ...
 
# 2. PATCH the connection with the new evidence
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "NEW_KEY..." },
    "verification_evidence_id": "fresh-evidence-id"
  }'

La connexion reste en place — il n’est pas nécessaire de réimporter les numéros.

Étapes suivantes#