Utilisez vos propres numéros (VoIP, API)

Les numéros de démonstration conviennent au prototypage, mais le trafic en production doit utiliser des numéros que vous possédez via votre propre fournisseur VoIP. Ce guide vous présente le flux en trois étapes : tester les identifiants → créer la connexion → importer les numéros → vérifier.

Le tableau de bord propose une version guidée de l’ensemble de ce flux sous Connexions → VoIP (/dashboard/voip-connections) : une configuration guidée Telnyx qui vous accompagne dans la création du compte et des clés API, un parcours de connexion à un compte existant et un formulaire SIP manuel avec un générateur de guide de configuration par IA.

Fournisseurs pris en charge

Fournisseur	id `provider`	Notes
Twilio	`twilio`	Clé API + secret
Telnyx	`telnyx`	Clé API ; intégration guidée disponible (`setup_method: guided_telnyx`)
SignalWire	`signalwire`	Bientôt disponible — connectez-vous via SIP manuel dès aujourd’hui
Vonage	`vonage`	Bientôt disponible — connectez-vous via SIP manuel dès aujourd’hui
SIP manuel	`manual`	Tout trunk SIP — utilisez votre propre configuration

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 que vous transmettez à 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" }
  }'

Response

{
  "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 quelle étape a échoué. Corrigez la configuration côté fournisseur (affectation du trunk, liste d’autorisation IP, autorisation sortante), 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 texte brut par les GET suivants — pour les renouveler, exécutez un nouveau test et effectuez un PATCH avec les nouvelles preuves.

3. Lister et importer des numéros

Examinez les numéros visibles avec 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 que vous souhaitez :

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 ; pour acheminer réellement les appels via celui-ci, une vérification aller-retour est nécessaire (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 précisément 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 Traiter les appels entrants et Passer des appels sortants.

Rotation des identifiants

Lorsqu’une clé fournisseur est renouvelée, exécutez à nouveau le flux tester puis mettre à 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

Référence des connexions VoIP

Chaque champ des réponses de connexion, de preuve et d’importation.

Référence des numéros de téléphone

Affectez des agents, transférez entre organisations, libérez des numéros.

Passer des appels sortants

Maintenant que vous possédez le numéro, commencez à passer des appels sortants.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Utilisez vos propres numéros (VoIP, API)

Fournisseurs pris en charge

1. Tester les identifiants

2. Créer la connexion

3. Lister et importer des numéros

4. Vérifier chaque numéro importé

5. Affecter des agents et prendre un appel

Rotation des identifiants

Étapes suivantes

Référence des connexions VoIP

Référence des numéros de téléphone

Passer des appels sortants

​Fournisseurs pris en charge

​1. Tester les identifiants

​2. Créer la connexion

​3. Lister et importer des numéros

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

​5. Affecter des agents et prendre un appel

​Rotation des identifiants

​Étapes suivantes

Référence des connexions VoIP

Référence des numéros de téléphone

Passer des appels sortants

Fournisseurs pris en charge

1. Tester les identifiants

2. Créer la connexion

3. Lister et importer des numéros

4. Vérifier chaque numéro importé

5. Affecter des agents et prendre un appel

Rotation des identifiants

Étapes suivantes