Developer cookbook

Apportez vos propres numéros (VoIP, API)

Connectez Twilio ou Telnyx — ou n’importe quel trunk 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 eux.

Les numéros de démonstration conviennent au prototypage, mais le trafic de production doit utiliser des numéros que vous possédez via votre propre fournisseur VoIP. Ce guide décrit le flux en trois étapes : 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 qui a échoué. Corrigez la configuration côté fournisseur (affectation du trunk, liste d’adresses IP autorisées, autorisation des appels sortants), puis réessayez.

2. Créer 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 sont stockés côté serveur et ne sont jamais renvoyés en clair par les requêtes GET suivantes — pour effectuer une rotation, exécutez un nouveau test et effectuez un PATCH avec les nouvelles preuves.

3. Lister et importer les numéros#

Inspectez les numéros associés à vos identifiants qui ne se trouvent 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 de votre choix :

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 source="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 aller-retour (contrôle d’appel entrant + sonde d’autorisation sortante).

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". En cas d’échec, la réponse indique ce qui a échoué — corrigez-le (souvent une affectation de trunk manquante dans le tableau de bord du fournisseur), puis relancez l’appel.

5. Affecter des agents et prendre un appel#

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

Rotation des identifiants#

Lorsqu’une clé de fournisseur est renouvelée, relancez 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#