Passer des appels
Votre PBX, l'autocommutateur qui achemine vos appels, envoie un SIP INVITE vers le domaine SIP du trunk pour passer un appel. Bird vérifie la requête, la route vers un opérateur et relaie l'audio. Cette page couvre les prérequis, les champs de la requête, l'authentification et le coût.
Avant de passer un appel
Quatre éléments doivent être prêts, dans n'importe quel ordre, et trois d'entre eux sont de votre ressort :
- Un trunk qui accepte votre trafic. Créez un trunk SIP et activez les appels sortants. Ajoutez les plages IP de votre équipement, une clé API autorisée, ou les deux. Les clients qui ne peuvent pas conserver un secret de longue durée peuvent utiliser un identifiant de session.
- Un identifiant d'appelant vérifié. Enregistrez le numéro que vous présentez et effectuez son appel de vérification, qui est le moyen par lequel un espace de travail prouve qu'il possède les numéros qu'il présente. La vérification ne garantit pas la livraison de bout en bout du CLI ni la connexion de l'appel lorsque le CLI n'est pas un numéro acquis via Bird : consultez la clause de non-responsabilité sur la vérification et la livraison CLI.
- Le pays de destination activé. Activez les pays que vous desservez sur la page Destinations.
- Le routage associé à votre espace de travail. Bird le configure pour vous, en choisissant quels opérateurs desservent quelles destinations. Tant qu'il n'est pas en place, les appels sont refusés avec routing_not_configured, l'une des raisons couvertes par Appels rejetés.
Ce que Bird attend sur l'INVITE
Envoyez la requête vers le domaine SIP de votre trunk sur l'un de ses ports pris en charge. Deux en-têtes contiennent tout ce dont Bird a besoin :
| En-tête | Ce que Bird en fait |
|---|---|
| To | Le numéro appelé. Bird lit son pays pour choisir un opérateur et tarifer l'appel |
| From | Le numéro que vous présentez comme appelant. Il doit être un identifiant d'appelant vérifié dans cet espace de travail |
Utilisez des numéros internationaux complets au format E.164, un + initial suivi de l'indicatif pays et du numéro national, sur les deux en-têtes. C'est la forme que Bird enregistre sur l'appel et celle attendue par sa correspondance de destination.
En dehors de ces deux en-têtes, il s'agit d'un appel SIP ordinaire, sans en-tête personnalisé dans aucun sens.
Authentifier chaque appel
Ce que traverse un appel dépend de la manière dont le trunk est ouvert :
- Liste d'autorisation IP uniquement. Une seule requête. Bird compare l'adresse source à la liste et route l'appel, sans défi à relever.
- Clés API autorisées uniquement. Bird demande d'abord un mot de passe à l'appel, via l'échange Digest SIP.
- Les deux. L'adresse source est vérifiée avant que Bird ne lance un défi, de sorte qu'un appel provenant d'une adresse non listée est refusé quels que soient les identifiants qu'il présente.
- Identifiants de session activés. Bird lance un défi à l'appel quelle que soit son origine, même une adresse non couverte par la liste d'autorisation, et un identifiant émis quelques minutes plus tôt y répond. Les équipements déjà admis par la liste d'autorisation sur un trunk sans clés autorisées continuent de se connecter sans défi.
Lorsque le trunk a des clés API autorisées, votre système téléphonique répond avec un hash du secret de la clé API plutôt qu'avec le secret lui-même, ce qui correspond au fonctionnement de l'authentification Digest SIP :
- Votre PBX envoie le INVITE.
- Bird répond 407 Proxy Authentication Required avec une ligne de défi par algorithme proposé par le trunk, SHA-256 puis MD5 par défaut.
- Votre PBX renvoie le INVITE avec un en-tête Proxy-Authorization calculé avec le nom d'utilisateur bird et le secret de la clé API comme mot de passe.
- Bird vérifie la réponse et poursuit le routage.
Un en-tête Proxy-Authorization préemptif est envoyé avant le défi, votre équipement doit donc choisir un algorithme que le trunk propose. Si le trunk dispose aussi d'une liste d'autorisation IP, la requête doit tout de même provenir d'une adresse listée.
Bird répond à un échange échoué au niveau de la couche SIP, de sorte que la tentative est rejetée avant que la plateforme ne crée un enregistrement d'appel. Si vos appels sont totalement absents du journal des appels, examinez les identifiants plutôt que le routage.
Attestation des appels
Les appels vers les États-Unis et la France portent une attestation STIR/SHAKEN. Les opérateurs utilisent cette signature pour étiqueter les appels. Bird applique le niveau B par défaut sans configuration supplémentaire. Contactez le support pour demander le niveau A.
Quand un appel est refusé
Bird vérifie l'identifiant d'appelant, la destination, les limites et le solde du portefeuille avant de composer vers un opérateur. Un refus parvient à votre système téléphonique sous la forme SIP 503 ; la cause précise reste sur l'enregistrement d'appel authentifié. Ouvrez l'appel dans le journal des appels, ou consultez les appels rejetés pour chaque raison et résolution.
Résolvez la cause enregistrée avant de réessayer. Par exemple, calls_per_second_exceeded persiste tant que vous ne ralentissez pas la cadence de numérotation.
Les appels d'urgence ne sont pas acheminés
Bird Voice n'achemine pas les appels vers les services d'urgence. Un appel vers 112, 911, 999 ou tout autre numéro d'urgence est refusé, sur chaque trunk, dans chaque pays. Votre système téléphonique doit joindre les services d'urgence par un autre chemin.
Ce comportement ne dépend ni de votre forfait, ni de votre solde, ni de vos destinations. Configurez votre système téléphonique pour router les appels d'urgence via un service qui les prend en charge, comme une ligne PSTN locale, une passerelle sur site ou un autre fournisseur. Testez cette route. Bird renvoie 503 pour un appel d'urgence refusé, ce qui permet à un système téléphonique disposant d'une autre route dans son plan de numérotation de la tenter.
Les services d'urgence dépendent de la localisation enregistrée de l'appelant, que Bird ne stocke pas pour un trunk. Ne comptez pas sur une route Bird pour les appels d'urgence.
Coût et facturation
La voix est prépayée depuis le portefeuille de votre organisation, comme les autres canaux :
- Le temps facturable court de la réponse à la fin, quelle que soit la durée de la sonnerie. L'enregistrement d'appel l'affiche à côté de la Durée totale, qui court à partir du moment où Bird a reçu l'appel.
- Le tarif dépend du pays de destination. Votre grille tarifaire indique le prix de chaque pays dans la devise du portefeuille. Un tarif définit un temps minimum facturé et l'incrément utilisé après ce minimum. Par exemple, un tarif avec un minimum d'une minute et des incréments de six secondes facture un appel de 10 secondes comme une minute.
- Le portefeuille est vérifié avant que l'opérateur ne soit appelé. Un appel que votre solde ne peut pas couvrir est refusé avec insufficient_balance d'emblée plutôt que facturé après coup. Gardez une réserve, ou activez les rechargements automatiques.
- Une limite quotidienne de dépenses vocales s'applique. Au-delà, les appels sont refusés avec daily_spend_exceeded jusqu'au début du jour UTC suivant. Le montant dépend de votre forfait.
- Le coût apparaît sur l'appel une fois celui-ci tarifé, à pleine précision, hors taxes.
Pour totaliser les dépenses sur l'ensemble des appels, exportez la liste d'appels filtrée en CSV depuis la page Calls, ou consultez vos factures et consommation.
Étapes suivantes
| Page | Ce qu'elle couvre |
|---|---|
| Journal des appels | Consulter, filtrer et exporter vos enregistrements d'appels |
| Événements vocaux | Recevoir les résultats d'appels poussés vers vos propres systèmes |
| Moyens de paiement et portefeuille | Rechargement, rechargements automatiques et fonctionnement du portefeuille |
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Comprendre le conceptWhat is a voice API?Explorer la fonctionnalitéVoiceGuide d'implémentationVoice overview
Obtenir un guide d'implémentation