Passer des appels

Votre PBX envoie une requête INVITE SIP au domaine SIP du trunk pour passer un appel. Bird vérifie la requête, l’achemine vers un opérateur et relaie l’audio. Cette page présente les prérequis, les champs de la requête, l’authentification et le coût.

Pour lancer un appel depuis votre application via HTTP, utilisez le guide de création d’appels. Cette méthode exécute une séquence Bird publiée une fois l’appel décroché.

Avant de passer un appel

Le guide Configurer un trunk SIP détaille dans l’ordre la configuration complète d’un trunk, pour les deux sens d’appel.

Quatre conditions doivent être remplies, dans n’importe quel ordre. Trois d’entre elles sont à configurer de votre côté :

• 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 admissible. Utilisez un numéro Bird attribué à cet espace de travail, ou enregistrez un numéro externe et effectuez son appel de vérification. La vérification ne garantit ni la transmission de bout en bout du CLI ni l’établissement de l’appel lorsque le CLI n’est pas un numéro obtenu auprès de Bird : consultez la clause de non-responsabilité relative à la vérification et à la transmission du CLI.
• Le pays de destination activé. Activez les pays que vous desservez sur la page Destinations.
• Un routage associé à votre espace de travail. Bird le configure pour vous en choisissant les opérateurs qui desservent chaque destination. Tant que ce routage n’est pas en place, les appels sont refusés avec routing_not_configured, l’un des motifs décrits dans Appels rejetés.

Ce que Bird attend dans l’INVITE

Envoyez la requête au domaine SIP de votre trunk sur l’un de ses ports pris en charge. Bird en lit trois parties :

Écrivez les numéros au format international E.164, avec un + initial suivi de l’indicatif du pays et du numéro national. Bird accepte aussi le même numéro avec 00 à la place de +, ou uniquement sous forme de chiffres commençant par l’indicatif du pays. Bird interprète les chiffres sans + ni 00 comme commençant par un indicatif de pays. Un numéro au format national n’est donc pas interprété comme le numéro souhaité. N’ajoutez pas de préfixe technique au numéro appelé.

En dehors de ces exigences, il s’agit d’un appel SIP ordinaire, et vous n’avez pas besoin d’envoyer d’en-tête personnalisé.

Proposez G.711, en loi A ou en loi µ, dans votre SDP. Envoyez les tonalités du clavier (DTMF) sous forme d’événements téléphoniques RFC 4733. Bird retire les autres codecs, tels que G.729 ou Opus, de l’offre envoyée à l’opérateur. Incluez donc G.711 dans chaque offre.

Les flux multimédias utilisent RTP sans chiffrement. SRTP n’est pas pris en charge. TLS sur le port 5061 chiffre la signalisation, mais l’audio reste non chiffré.

Authentification de chaque appel

Les étapes suivies par un appel dépendent des accès autorisés sur le trunk :

• Liste d’adresses IP autorisées uniquement. Une seule requête suffit. Bird vérifie que l’adresse source figure dans la liste et achemine l’appel, sans demander de réponse à un défi d’authentification.
• Clés API autorisées uniquement. Bird demande d’abord un mot de passe pour l’appel, au moyen de l’échange Digest SIP.
• Les deux. Les appels utilisant une clé API autorisée doivent aussi provenir d’une adresse figurant dans la liste. Lorsque les identifiants de session sont activés, ils permettent l’accès par une voie distincte, décrite ci-dessous.
• Identifiants de session activés. Bird soumet l’appel à un défi d’authentification, quelle que soit sa provenance, même si son adresse ne figure pas dans la liste des adresses autorisées. Un identifiant émis quelques minutes auparavant permet d’y répondre. Les équipements déjà admis par la liste des adresses autorisées sur un trunk sans clés autorisées continuent à se connecter sans défi d’authentification.

Lorsque le trunk dispose de clés API autorisées, votre système téléphonique répond avec un hachage du secret de la clé API, plutôt qu’avec le secret lui-même. C’est le principe de l’authentification Digest SIP :

1. Votre PBX envoie la requête INVITE.
2. Bird répond par 407 Proxy Authentication Required, avec une ligne de défi d’authentification par algorithme proposé par le trunk : SHA-256 puis MD5 par défaut.
3. Votre PBX renvoie la requête INVITE avec un en-tête Proxy-Authorization calculé à partir du nom d’utilisateur bird et du secret de la clé API comme mot de passe.
4. Bird vérifie la réponse et poursuit le routage.

Un en-tête Proxy-Authorization préemptif est envoyé avant le défi d’authentification. Votre équipement doit donc choisir un algorithme que le trunk propose. Pour l’authentification par clé API, un trunk doté d’une liste d’adresses IP autorisées exige toujours que la requête provienne d’une adresse de cette liste.

Bird répond à un échec de l’échange d’authentification au niveau SIP. La tentative est donc refusée avant que la plateforme ne crée un enregistrement d’appel. Si vos appels n’apparaissent pas du tout dans le journal des appels, vérifiez 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 l’assistance pour demander le niveau A.

Lorsqu’un appel est refusé

Bird vérifie l’identifiant de l’appelant, la destination, les limites et le solde du portefeuille avant de lancer l’appel auprès d’un opérateur. Votre système téléphonique reçoit le refus sous la forme d’une réponse SIP 503 ; la cause précise reste consignée dans l’enregistrement de l’appel, accessible après authentification. Ouvrez l’appel dans le journal des appels, ou consultez les appels rejetés pour connaître chaque motif et sa résolution.

Résolvez la cause consignée avant de réessayer. Par exemple, calls_per_second_exceeded persiste tant que vous ne réduisez pas la cadence des appels.

Les réponses à un appel enregistré par Bird contiennent un en-tête X-BIRD-CALL-ID avec le Leg ID de l’appel (vcl_…). Cela inclut la réponse 503 d’un refus dont le motif est consigné. Consultez l’enregistrement avec GET /v1/voice/legs/{leg_id}, ou communiquez cet identifiant à l’assistance.

Les appels d’urgence ne sont pas acheminés

Bird Voice n’achemine pas les appels vers les services d’urgence. Tout appel au 112, au 911, au 999 ou à tout autre numéro d’urgence est refusé, sur chaque trunk et dans tous les pays. Votre système téléphonique doit joindre les services d’urgence par une autre voie.

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 acheminer les appels d’urgence par un service qui les prend en charge, comme une ligne PSTN locale, une passerelle sur site ou un autre fournisseur. Testez cette voie. Bird renvoie 503 lorsqu’un appel d’urgence est refusé. Cela permet à un système téléphonique disposant d’une autre voie dans son plan de numérotation de l’essayer.

Les services d’urgence dépendent de la localisation enregistrée de l’appelant, que Bird ne conserve pas pour un trunk. Ne comptez pas sur une route Bird pour les appels d’urgence.

Coût et facturation

Comme les autres canaux, Voice est prépayé à partir du portefeuille de votre organisation :

• La durée facturable s’étend du décrochage à la fin de l’appel, quelle que soit la durée de sonnerie préalable. La fiche de l’appel l’affiche à côté de Total duration, qui commence dès que Bird reçoit l’appel.
• Le tarif dépend du pays de destination. Votre grille tarifaire indique le prix pour chaque pays dans la devise du portefeuille. Un tarif définit une durée minimale facturée et le palier appliqué au-delà de ce minimum. Par exemple, avec un minimum d’une minute et des paliers de six secondes, un appel de 10 secondes est facturé une minute.
• Le portefeuille est vérifié avant d’appeler l’opérateur. Un appel que votre solde ne peut pas couvrir est refusé d’emblée avec insufficient_balance, plutôt que de vous être facturé après coup. Gardez une réserve ou activez les recharges automatiques.
• Une limite de dépenses quotidiennes s’applique à la voix. Au-delà, les appels sont refusés avec daily_spend_exceeded jusqu’au début du jour UTC suivant. Un espace de travail peut aussi définir une limite quotidienne par pays de destination sous Voice > Destinations. Chaque appel doit respecter les deux limites. Le montant dépend de votre forfait.
• Le coût apparaît sur la fiche de l’appel une fois son tarif calculé, avec sa précision complète, hors taxes.

Pour consulter les frais de l’ensemble des appels, utilisez Consommation, dépenses et factures. L’export CSV Legs comprend les durées et la durée facturable, mais ne contient pas de colonne de coût.

Étapes suivantes