Apportez vos propres numéros

Ce document décrit comment intégrer des numéros de téléphone à la plateforme de validation des appels d’Audact par deux voies distinctes : les numéros provisionnés par Audact (gérés via Telnyx) et les trunks Bring-Your-Own (BYO) (gérés via votre propre fournisseur de téléphonie).

Deux types de numéros

Audact prend en charge deux façons fondamentales de fournir des numéros de téléphone pour le routage des appels entrants :

Type 1 : numéros provisionnés par Audact (Telnyx)

Audact gère l’ensemble du cycle de vie du numéro grâce à sa relation avec l’opérateur Telnyx.

Acquisition : vous demandez des numéros par le processus de dépôt de documents KYC et de commande de numéros décrit dans Provisionnement des numéros et KYC. Audact chiffre vos documents de conformité, les soumet à Telnyx pour approbation et, une fois l’approbation obtenue, vous pouvez commander des DID dans toute combinaison pays/type couverte par cette approbation.

Cycle de vie : les numéros sont conservés dans le pool d’Audact, attribués aux agents via l’API de la plateforme et facturés automatiquement par le compte Telnyx d’Audact. La plateforme configure la connexion au trunk SIP Telnyx en votre nom — vous ne fournissez jamais de paramètres de connexion.

Fin de vie : deux opérations existent :

• Libération : supprime l’attribution à l’agent et remet le numéro dans le pool (DELETE /v1/numbers/{id}/release). Le DID reste la propriété d’Audact et peut être réattribué ultérieurement.
• Suppression : supprime définitivement le numéro et restitue le DID à l’inventaire de Telnyx (DELETE /v1/numbers/{id}). Cette opération est irréversible ; le numéro disparaît de la plateforme et du pool de l’opérateur.

Connexion : automatique. Vous faites pointer votre compte Telnyx vers l’hôte d’entrée SIP affiché dans votre tableau de bord (récupéré depuis GET /v1/byo/config), et Audact s’occupe du reste.

Type 2 : trunk Bring-Your-Own (BYO)

Vous gérez l’acquisition des numéros et la relation avec le fournisseur de téléphonie ; Audact accepte les appels entrants acheminés par votre trunk SIP.

Acquisition : les numéros sont achetés directement auprès de votre fournisseur de téléphonie (Twilio, Telnyx ou tout fournisseur SIP générique). Vous contrôlez la facturation, la relation avec l’opérateur et le pool de numéros.

Cycle de vie : vous êtes propriétaire des numéros et pouvez les réattribuer ou les libérer à la discrétion de votre fournisseur. Audact ne provisionne, ne facture ni ne gère ces DID — il ne fait qu’acheminer les appels qui y arrivent.

Fin de vie : vous libérez les numéros auprès de votre opérateur. Audact cesse simplement d’acheminer les appels vers ce numéro.

Connexion : vous configurez l’URI d’origination du trunk SIP pour qu’elle pointe vers l’entrée SIP d’Audact (affichée dans votre tableau de bord depuis GET /v1/byo/config). Audact valide les appels entrants par rapport à votre pool de numéros BYO configurés et les achemine vers les agents appropriés.

Configuration du type 1 : numéros provisionnés par Audact

Consultez Provisionnement des numéros et KYC pour le cycle de vie complet. En résumé :

1. Téléversez les documents KYC avec POST /v1/kyc/documents
2. Créez un ensemble de documents avec POST /v1/kyc/document-sets (Telnyx l’approuve de manière asynchrone)
3. Une fois l’approbation obtenue, passez une commande de numéros avec POST /v1/numbers/orders
4. Attribuez les numéros aux agents avec POST /v1/numbers/{id}/assign
5. Audact configure automatiquement le trunk SIP Telnyx

Aucune configuration manuelle de trunk SIP n’est nécessaire pour les numéros de type 1.

Configuration du type 2 : trunks Bring-Your-Own

Votre trunk SIP origine les appels vers l’entrée SIP d’Audact. Les sections suivantes décrivent trois configurations courantes de fournisseurs et un modèle SIP générique.

Interroger la configuration de votre entrée SIP

Avant de configurer un trunk BYO, récupérez les paramètres d’entrée SIP de votre tenant :

curl -X GET https://api.audact.ai/v1/byo/config \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Réponse :

{
  "sip_ingress_host": "sip.us.audact.ai",
  "sip_ingress_port": 5060,
  "allowed_source_cidrs": ["203.0.113.0/24"],
  "healthy_numbers": ["+14155551234", "+14155551235"],
  "failed_numbers": []
}

Utilisez ci-dessous sip_ingress_host et sip_ingress_port.

Connecter un trunk Twilio

Le produit SIP Trunking de Twilio vous permet d’originer des appels vers n’importe quel serveur SIP externe.

1. Créer un trunk SIP Twilio

1. Connectez-vous à la Twilio Console → Elastic SIP Trunks
2. Cliquez sur + pour créer un nouveau trunk
3. Choisissez un Friendly Name (par ex. audact-sip-trunk)
4. Cliquez sur Create

2. Configurer l’URI d’origination

Dans les paramètres du trunk, sous Originating SIP Address :

1. Cliquez sur + pour ajouter une URI d’origination
2. Saisissez : sip:${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT} (par ex. sip:sip.us.audact.ai:5060)
3. Réglez Priority sur 10 (plus la valeur est basse, plus la priorité est élevée)
4. Réglez Weight sur 100
5. Laissez Enabled coché
6. Cliquez sur Add

3. Créer une liste d’identifiants (si nécessaire)

Si vous devez envoyer des identifiants d’authentification SIP à Audact :

1. Dans le trunk, faites défiler jusqu’à Credential List
2. Cliquez sur + pour ajouter des identifiants
3. Saisissez le nom de votre liste d’identifiants (par ex. audact-credentials)
4. Sélectionnez Credential Type : SIP Credentials
5. Saisissez le Username et le Password (à coordonner avec le support Audact)
6. Cliquez sur Create
7. Associez la liste d’identifiants au trunk

Remarque : la plupart des trunks Twilio utilisent l’authentification par IP (liste d’autorisation d’adresses IP) plutôt que des identifiants. Vérifiez ce qui s’applique à votre configuration.

4. Configurer le routage des numéros de téléphone

Pour chaque numéro de téléphone que vous souhaitez router via ce trunk :

1. Dans la Twilio Console, allez dans Phone Numbers → Active Numbers
2. Sélectionnez le numéro
3. Sous Voice & Fax, réglez :
   • Configure With : SIP Trunk
   • SIP Trunk : sélectionnez le audact-sip-trunk que vous venez de créer
4. Enregistrez

5. Autoriser les IP d’Audact (facultatif)

Si votre trunk Twilio utilise l’authentification par IP :

1. Dans les paramètres du trunk, repérez Originating SIP Address
2. Notez les éventuelles restrictions d’IP sur l’URI d’origination
3. Demandez au support Audact la liste des IP des serveurs SIP sortants
4. Ajoutez-les à la liste d’autorisation d’IP de votre trunk Twilio

Connecter un trunk Telnyx

Le produit SIP Trunking de Telnyx est similaire à celui de Twilio. Si vous avez déjà des numéros Telnyx mais souhaitez utiliser le trunking BYO (plutôt que des numéros provisionnés par Audact), suivez ce guide.

1. Créer une connexion SIP Telnyx

1. Connectez-vous au Telnyx Portal → Connections → SIP Connections
2. Cliquez sur Create SIP Connection
3. Choisissez un Connection Name (par ex. audact-sip-connection)
4. Sous Outbound, ajoutez une Originating SIP Address :
   • Saisissez : sip:${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT} (par ex. sip:sip.us.audact.ai:5060)
5. Cliquez sur Create

2. Configurer l’authentification

Option A : authentification par IP

1. Dans les paramètres de votre connexion Telnyx, repérez IP Authentication
2. Ajoutez les IP des serveurs SIP d’Audact à la liste d’autorisation
3. Demandez au support Audact les plages d’IP exactes

Option B : identifiants SIP

1. Dans les paramètres de votre connexion, sous Authentication, sélectionnez Username & Password
2. Saisissez votre Username (par ex. l’identifiant de votre tenant ou celui de votre clé API)
3. Définissez un Password
4. Cliquez sur Save
5. Communiquez ces identifiants à Audact (de manière sécurisée)

3. Attribuer les numéros de téléphone

Pour chaque numéro BYO, attribuez-le à la connexion SIP :

1. Allez dans Inventory → Phone Numbers
2. Sélectionnez un numéro
3. Sous Routing, réglez :
   • Connection Type : SIP Connection
   • Connection : sélectionnez votre audact-sip-connection
4. Saisissez l’URI Sip Termination : sip:${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT}
5. Enregistrez

4. Configurer la facturation

Assurez-vous que la facturation est configurée directement auprès de Telnyx — Audact ne vous facture pas les numéros BYO. Telnyx vous facture les minutes, la terminaison et la location des numéros.

Connecter un trunk SIP générique

Si votre fournisseur n’est ni Twilio ni Telnyx, utilisez ce modèle d’origination SIP générique.

Prérequis

• Votre fournisseur SIP autorise l’origination sortante vers n’importe quel serveur SIP externe
• Vous disposez d’identifiants SIP sortants ou d’un accès à une liste d’autorisation d’IP
• Votre fournisseur prend en charge le format de numéro de téléphone E.164 dans les en-têtes SIP INVITE

Étapes de configuration

1. Ajoutez Audact comme pair d’origination dans le portail de votre fournisseur :

   • Peer Address : ${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT} (par ex. sip.us.audact.ai:5060)
   • Protocole : SIP (UDP ou TCP, à coordonner avec Audact)
   • Port : 5060 (par défaut ; à confirmer auprès de votre fournisseur et d’Audact)

2. Authentification (au choix) :

   Option A : authentification par IP

   • Ajoutez l’IP publique de votre serveur ou passerelle SIP à la liste d’autorisation d’Audact
   • Demandez au support Audact leur plage d’IP de serveurs SIP
   • Ajoutez les IP d’Audact à la liste d’autorisation de votre fournisseur

   Option B : authentification Digest (nom d’utilisateur et mot de passe)

   • Définissez le Username : votre clé API, l’identifiant de votre tenant ou un identifiant attribué par le fournisseur
   • Définissez le Password : un secret robuste
   • Assurez-vous que votre fournisseur envoie les identifiants dans le SIP INVITE ou REGISTER
   • Communiquez les identifiants au support Audact afin que nous puissions les valider

3. Configurer les règles d’origination :

   • Pour chaque numéro de téléphone, acheminez le trafic entrant vers le pair Audact
   • Assurez-vous que le SIP INVITE contient le numéro au format E.164 dans l’en-tête To (par ex. To: <sip:+14155551234@sip.us.audact.ai>)

4. Tester la connexion :

   • Vérifiez que les paquets SIP parviennent à Audact en surveillant les journaux d’appels de votre fournisseur
   • Consultez le tableau de bord Audact pour voir si l’appel arrive (l’état de santé doit passer de unverified à healthy)

États de santé du trunk

Une fois un trunk BYO configuré, Audact suit son état de santé. Utilisez ces états pour diagnostiquer les problèmes de connexion.

Signification des états de santé

Vérifier l’état du trunk

Utilisez le point de terminaison GET /v1/byo/config pour consulter l’état de santé du trunk :

curl -X GET https://api.audact.ai/v1/byo/config \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

La réponse inclut health_status et last_check_timestamp pour chaque trunk.

Procédure de dépannage

1. Vérifier la résolution DNS :

   bash

   nslookup ${SIP_INGRESS_HOST}

   Le nom doit être résolu vers l’IP de votre serveur SIP.

2. Tester la connectivité SIP depuis votre serveur :

   bash

   # Using a SIP client or tool (e.g., sipvious, sipp)
   sipp -sf register.xml ${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT}

3. Vérifier les règles de pare-feu :

   • Assurez-vous que UDP/TCP 5060 est ouvert entre votre fournisseur et Audact
   • Confirmez que la plage d’IP d’Audact figure dans la liste d’autorisation de votre côté (si vous utilisez l’authentification par IP)

4. Examiner les journaux SIP :

   • Consultez les journaux SIP de votre fournisseur pour repérer les rejets ou délais d’attente sur les INVITE
   • Consultez les journaux d’erreurs SIP entrants d’Audact dans le tableau de bord

5. Tester un appel :

   • Passez un appel de test depuis n’importe quel téléphone vers l’un de vos numéros BYO
   • Observez le déroulement de l’appel dans le tableau de bord Audact
   • Vérifiez l’état de santé : il doit passer de unverified à healthy après le premier appel réussi

Facturation et responsabilités du trunk BYO

Combiner les types de numéros

Un tenant peut utiliser simultanément des trunks provisionnés par Audact et des trunks BYO. Par exemple :

• Attribuez des numéros provisionnés par Audact (+1415..., +44204...) à certains agents
• Routez des numéros BYO (+1212... de Twilio, +61... de Telnyx en BYO) vers d’autres agents
• Audact achemine tous les appels entrants de manière appropriée selon le DID

Aucune configuration particulière n’est nécessaire — configurez simplement les deux types en parallèle. Le point de terminaison GET /v1/byo/config renvoie à la fois les trunks gérés par Audact et les trunks BYO.