FAQ API Voix
Qu'est-ce que Bird Voice ?
Bird Voice vous permet de passer des appels vers des numéros de téléphone via un trunk SIP. Votre système téléphonique se connecte à Bird, et Bird achemine chaque appel via un opérateur vers le réseau téléphonique public (le PSTN). Vous fournissez votre propre PBX ou softphone ; Bird gère la partie opérateur.
En combien de temps puis-je passer mon premier appel ?
Environ dix minutes. Créez un trunk SIP, vérifiez un identifiant d'appelant, activez le pays de destination et dirigez votre système téléphonique vers l'adresse du trunk. Le guide du premier appel vous accompagne tout au long du processus.
De quoi ai-je besoin avant de pouvoir appeler ?
Trois éléments de votre côté : un trunk SIP avec votre équipement autorisé (par plage IP ou clé API), un identifiant d'appelant vérifié (le numéro que vous présentez comme appelant), et le pays de destination activé. Bird associe le routage à votre workspace, ce qui constitue le quatrième prérequis et est géré côté Bird.
Ai-je besoin d'un matériel spécial ?
Non. Tout système téléphonique compatible SIP fonctionne : un softphone comme Zoiper ou Linphone sur un ordinateur portable, un PBX comme Asterisk ou FreeSWITCH, ou un système commercial comme 3CX ou FreePBX. Bird vous attribue un domaine SIP, et vous dirigez votre équipement vers celui-ci.
Puis-je passer des appels depuis le navigateur ?
Oui. Vous pouvez passer des appels depuis l'application Phone du tableau de bord en utilisant WebRTC.
Comment les appels vocaux sont-ils tarifés ?
Par appel, à un tarif qui dépend du pays de destination. Chaque tarif comporte un incrément de facturation : un temps minimum facturé, puis le palier d'arrondi appliqué ensuite. Un tarif avec un minimum d'une minute et des paliers de six secondes facture un appel de 10 secondes pour une minute entière.
Quand la facturation commence-t-elle ?
Le temps facturable court à partir du moment où le numéro appelé décroche jusqu'à la fin de l'appel. Le temps de sonnerie n'est pas facturé, donc un appel sans réponse ne coûte rien.
La voix est-elle prépayée ou postpayée ?
Prépayée, depuis le portefeuille de votre organisation. Bird vérifie votre solde avant de contacter l'opérateur, de sorte qu'un appel que votre portefeuille ne peut pas couvrir est refusé d'emblée avec insufficient_balance plutôt que facturé après coup.
Y a-t-il un plafond de dépenses quotidien ?
Oui. Un plafond de dépenses vocales quotidien s'applique par organisation et se réinitialise au début de chaque jour UTC. Au-delà, les appels sont refusés avec daily_spend_exceeded. Le montant dépend de votre forfait, et Bird peut l'augmenter sur demande.
Où puis-je voir le coût d'un appel ?
Ouvrez l'appel dans le journal des appels. Le coût apparaît sur l'enregistrement une fois la tarification effectuée, avec une précision complète, hors taxes. Pour les totaux sur plusieurs appels, exportez la liste filtrée au format CSV depuis la page Appels, ou consultez vos factures et votre consommation.
Quelles limites s'appliquent à mes appels ?
Trois plafonds : le nombre d'appels simultanés autorisés (appels simultanés), le nombre de nouveaux appels que vous pouvez initier par seconde (appels par seconde), et le montant que vous pouvez dépenser en voix par jour UTC (dépense journalière). Chacun est défini par organisation, et les montants dépendent de votre plan.
Que se passe-t-il lorsque j'atteins une limite ?
L'appel est refusé dès l'établissement, avant même qu'un opérateur ne soit contacté. L'enregistrement de l'appel indique quelle limite a été atteinte : concurrent_calls_exceeded, calls_per_second_exceeded ou daily_spend_exceeded. Votre système téléphonique reçoit un SIP 503.
Puis-je augmenter mes limites ?
Oui. Contactez le support pour demander un plafond d'appels simultanés ou d'appels par seconde plus élevé. Le plafond de dépense journalière dépend de votre plan et peut également être relevé.
Mon automate d'appels est refusé alors que j'ai largement de la marge en appels simultanés. Pourquoi ?
Vérifiez le motif indiqué dans l'enregistrement de l'appel. Un automate peut atteindre calls_per_second_exceeded sans être proche du plafond d'appels simultanés, car les deux limites sont indépendantes. Ralentissez la cadence de numérotation et réessayez ; réessayer immédiatement donne le même résultat.
Qu'est-ce qu'un SIP trunk ?
Un SIP trunk est la connexion entre votre système téléphonique et Bird. SIP (Session Initiation Protocol) est le langage utilisé par les systèmes téléphoniques pour établir des appels, et un trunk est la ligne sur laquelle ces appels transitent. Bird attribue une adresse de trunk à votre espace de travail, et vous dirigez votre système téléphonique vers celle-ci.
De combien de trunks ai-je besoin ?
La plupart des espaces de travail n'en ont besoin que d'un seul. Créez-en davantage si vous souhaitez des règles d'accès distinctes par site ou par système, car la liste d'adresses IP autorisées, les clés API autorisées et les paramètres Digest sont définis par trunk.
Quels paramètres de connexion mon PBX requiert-il ?
Le domaine SIP du trunk (copié depuis la page du trunk), le nom d'utilisateur bird et le mot de passe (le secret d'une clé API autorisée sur le trunk). Envoyez les appels vers le domaine SIP sur le port 5060 (UDP ou TCP) ou 5061 (TLS).
Puis-je restreindre qui envoie des appels vers mon trunk ?
Oui, avec une liste d'adresses IP autorisées, des clés API autorisées, ou les deux. Ajoutez les adresses publiques depuis lesquelles votre équipement envoie du SIP, ou exigez que chaque appel s'authentifie avec une clé API via SIP Digest. Les deux prennent effet dès l'appel suivant.
Que se passe-t-il lorsque je supprime un trunk ?
Le domaine SIP du trunk cesse immédiatement d'accepter de nouveaux appels. Les appels déjà en cours se poursuivent, et les enregistrements d'appels effectués via le trunk restent dans votre journal des appels.
Comment fonctionne l'authentification SIP Digest ?
Votre PBX envoie l'appel, Bird répond avec un défi 407, et votre PBX renvoie l'appel avec un en-tête Proxy-Authorization calculé à partir du nom d'utilisateur bird et du secret de votre clé API comme mot de passe. Votre PBX envoie un hash du mot de passe, jamais le mot de passe lui-même.
Quels algorithmes Digest sont pris en charge ?
SHA-256 et MD5. Bird propose SHA-256 en premier et MD5 en second par défaut, et votre PBX choisit le premier qu'il prend en charge. Si votre équipement ne gère que MD5 et traite mal un défi commençant par SHA-256, configurez le trunk en MD5 uniquement.
Puis-je utiliser à la fois la liste d'adresses IP autorisées et l'authentification par clé API ?
Oui. Lorsqu'un trunk dispose des deux, l'adresse source est vérifiée avant que Bird ne demande un mot de passe. Un appel provenant d'une adresse non répertoriée est donc refusé, quels que soient les identifiants qu'il transmet.
Comment effectuer la rotation d'une clé API sans interruption de service ?
Ajoutez d'abord la nouvelle clé au trunk, basculez votre équipement, puis révoquez l'ancienne. Révoquer ou supprimer une clé supprime immédiatement sa capacité d'authentification sur tous les trunks qui l'autorisaient.
Qu'est-ce qu'un caller ID ?
Un caller ID est un numéro de téléphone que votre workspace est autorisé à présenter comme appelant pour les appels sortants. Bird vérifie le numéro d'appel que votre équipement insère dans l'en-tête SIP From par rapport à cette liste pour chaque appel : les appels ne partent donc que sous des numéros que vous avez vérifiés.
Comment vérifier un caller ID ?
Ajoutez le numéro sur la page Numéros au format E.164. Bird passe immédiatement un appel de vérification vers ce numéro. Répondez à l'appel, écoutez le code à six chiffres et saisissez-le dans le tableau de bord. Vous disposez de cinq tentatives, et le numéro devient utilisable dès qu'une tentative est acceptée.
L'appel de vérification n'est jamais arrivé. Que faire ?
Si les tentatives sont épuisées, utilisez Obtenir un nouveau code sur la ligne du numéro pour recevoir un nouvel appel de vérification. Si le numéro est encore en attente de son code, supprimez l'identifiant de l'appelant et ajoutez à nouveau le numéro.
Comment vérifier un numéro qui sonne sur un système sans surveillance ?
Redirigez-le vers un téléphone que vous pouvez décrocher le temps de la vérification, puis rétablissez la configuration. Pour un numéro qui ne reçoit aucun appel, contactez le support.
Que se passe-t-il lorsque je supprime un caller ID ?
À partir de ce moment, tout appel présentant ce numéro est refusé avec caller_id_not_verified. Les appels déjà en cours continuent, et les enregistrements d'appels ayant utilisé ce numéro restent inchangés.
Pourquoi dois-je activer des pays avant d'appeler ?
La fraude téléphonique fonctionne en composant des numéros vers des pays coûteux que vous n'aviez jamais l'intention d'appeler. Les pays que vous activez sont ceux sur lesquels vous pouvez accumuler des frais : désactiver tous les autres limite votre exposition si quelqu'un s'introduit dans votre système téléphonique.
Comment activer un pays de destination ?
Trouvez le pays sur la page Destinations à l'aide de la barre de recherche (recherche par nom ou code à deux lettres) et activez son commutateur. Le changement s'applique immédiatement.
Que signifie le badge High risk ?
Les appels vers les pays à haut risque sont coûteux, et l'opérateur du numéro que vous composez perçoit une part du coût. Ce sont les pays qu'un attaquant cible s'il s'introduit dans un système téléphonique. Laissez-les désactivés sauf si vous y avez des activités, et vérifiez le tarif avant d'en activer un.
Un pays dont j'ai besoin est indiqué comme Not supported. Que faire ?
Contactez le support pour le faire ouvrir pour votre compte. Available signifie que vous pouvez l'activer ; Not supported signifie que Bird ne peut pas actuellement passer d'appels vers ce pays depuis votre compte.
Mon appel a échoué avec no_route_found alors que le pays est activé. Pourquoi ?
Un pays disponible peut encore avoir des destinations spécifiques en son sein que le routage ne couvre pas encore. Envoyez l'identifiant de l'appel au support et ils étendront le routage pour le couvrir.
Qu'attend Bird dans le SIP INVITE ?
Deux en-têtes : To (le numéro appelé) et From (le numéro que vous présentez comme appelant, qui doit être un identifiant d'appelant vérifié). Les deux doivent être des numéros internationaux complets au format E.164, soit un + initial suivi de l'indicatif pays et du numéro national. Aucun en-tête personnalisé n'est requis.
Qu'est-ce que l'attestation STIR/SHAKEN ?
STIR/SHAKEN est une signature que les opérateurs utilisent pour décider de laisser passer un appel sans étiquette. Les appels vers les États-Unis et la France l'intègrent automatiquement sans aucune configuration de votre part. Les appels portent le niveau B par défaut ; le niveau A (le plus fort) est disponible sur demande.
Mon appel a été refusé. Comment savoir pourquoi ?
Ouvrez l'appel dans le journal des appels. Votre système téléphonique ne reçoit qu'un simple SIP 503, mais le motif précis figure sur l'enregistrement de l'appel, accessible uniquement par vous. Un panneau au-dessus des détails indique la cause et renvoie vers le paramètre à corriger.
Dois-je réessayer un appel refusé ?
Seulement une fois la cause résolue. Un appel refusé pour calls_per_second_exceeded recevra la même réponse tant que vous ne ralentissez pas la cadence de numérotation. Consultez le motif de rejet avant de réessayer.
Quels sont les statuts d'appel existants ?
Cinq : Answered (le numéro appelé a décroché), No answer (l'appel a sonné sans réponse), Failed (l'appel n'a pas abouti, soit Bird l'a refusé, soit un opérateur l'a échoué), Rejected (l'opérateur a directement décliné l'appel) et Unknown (le résultat n'a pas pu être déterminé).
Comment distinguer un refus de Bird d'une défaillance de l'opérateur ?
Les deux apparaissent comme Failed. C'est le motif de rejet qui les différencie : seul un refus de Bird en comporte un. Un appel échoué avec un motif de rejet indique un problème de configuration de votre côté ou de celui de Bird ; un appel sans motif de rejet pointe généralement vers le numéro que vous avez composé.
Puis-je voir les appels en cours ?
Oui. L'onglet Live de la page Calls affiche les appels en cours sur vos trunks, avec un compteur. Un appel en direct s'affiche comme Ringing (en attente que l'autre partie décroche) ou In progress (connecté). L'onglet se rafraîchit toutes les quelques secondes.
Quelle est la différence entre la durée totale et le temps facturable ?
La durée totale s'étend du moment où Bird a reçu l'appel jusqu'au raccroché. Le temps facturable s'étend de la réponse au raccroché. L'écart correspond au temps de sonnerie sans réponse : un écart important mérite d'examiner ce que vous composez. Un appel sans réponse ne coûte rien.
Comment exporter les enregistrements d'appels ?
Trois méthodes : télécharger un CSV depuis la page Calls (exporte tous les enregistrements correspondant à vos filtres actuels, pas seulement la page visible), les consulter via l'API avec une clé API dotée du scope voice:read, ou utiliser le Bird CLI avec bird voice list.
Quels événements vocaux Bird émet-il ?
Trois : voice_call.initiated (Bird a accepté l'appel et commencé le routage), voice_call.answered (le numéro appelé a décroché) et voice_call.ended (l'appel est terminé, avec le résultat). Un appel sans réponse n'émet jamais l'événement answered.
Un appel refusé génère-t-il des événements ?
Un appel que Bird refuse après avoir accepté l'INVITE se termine tout de même par voice_call.ended, avec le statut failed et le sip_response_code 503. Chaque appel dont vous êtes informé de l'ouverture se ferme donc aussi. Un appel que Bird ne peut pas du tout admettre (rejeté au niveau de la couche SIP) ne produit aucun événement.
Les événements peuvent-ils arriver dans le désordre ?
Oui. Les livraisons ne sont pas ordonnées, donc answered peut vous parvenir après ended. Triez par le champ timestamp et laissez un événement arrivé plus tard avec un timestamp antérieur perdre.
Comment éviter de compter les événements en double ?
Dédupliquez sur l'en-tête HTTP webhook-id. Bird livre au moins une fois, et l'événement initiated d'un appel peut être publié plusieurs fois lorsqu'une tentative de signalisation est rejouée. Même appel, même étape, même webhook-id.
Où se trouvent le coût et le motif de rejet dans les événements ?
Ils figurent sur l'enregistrement de l'appel, pas dans l'événement. Un statut failed sur voice_call.ended ne vous indique pas si c'est Bird ou un opérateur qui en est la cause. Ouvrez l'appel dans le journal des appels pour consulter le motif de rejet ; le coût y apparaît une fois l'appel tarifé.
Mon appel n'apparaît pas du tout dans le journal des appels. Où est-il ?
Un appel que Bird ne peut pas admettre est rejeté au niveau SIP, avant qu'un enregistrement n'existe. Vérifiez quatre points : le trunk dispose d'une plage IP ou d'une clé API autorisant votre équipement, l'appel provient d'une adresse figurant dans la liste IP autorisée du trunk (derrière un NAT, il s'agit de l'adresse publique du routeur), les identifiants Digest sont corrects (nom d'utilisateur bird, le bon secret de clé API, un algorithme proposé par le trunk) et le domaine SIP correspond exactement au domaine du trunk.
Mon appel a échoué avec une raison de rejet. Que dois-je faire ?
Ouvrez l'appel dans le journal des appels. Le panneau au-dessus des détails indique la cause et renvoie vers le paramètre à corriger. Les sept raisons que vous pouvez résoudre sont source_not_allowed, caller_id_not_verified, destination_not_enabled, insufficient_balance, daily_spend_exceeded, concurrent_calls_exceeded et calls_per_second_exceeded.
Mon client répond au défi Digest avec MD5 et n'aboutit à rien.
Certains équipements gèrent mal un défi qui commence par SHA-256. Réglez l'algorithme Digest du trunk sur MD5 uniquement, et votre PBX recevra un défi qu'il comprend.
Les appels se connectent mais l'audio est unidirectionnel. Quel est le problème ?
Votre client est derrière un NAT (un routeur ou pare-feu qui réécrit les adresses) et le flux média est dirigé vers une adresse privée que l'autre partie ne peut pas atteindre. Activez la gestion NAT ou STUN de votre client pour qu'il annonce son adresse publique dans l'offre média.
La connexion SIP est-elle chiffrée ?
C'est possible. Bird prend en charge TLS sur le port 5061 pour la signalisation SIP, de sorte que l'établissement de l'appel est chiffré en transit. UDP et TCP sur le port 5060 ne sont pas chiffrés. Choisissez le transport correspondant à vos exigences de sécurité.
Comment vérifier qu'un webhook provient bien de Bird ?
Chaque événement est signé par HMAC. Vérifiez la signature avec le secret de votre endpoint avant d'agir sur le contenu, et renouvelez ce secret depuis le tableau de bord dès que nécessaire.
Où sont stockées mes données ?
Dans la région où votre organisation est hébergée, soit us1, soit eu1. Votre clé API porte cette information dans son préfixe (bk_us1_, bk_eu1_), ce qui permet aux SDK et au CLI de choisir automatiquement le bon endpoint sans configuration de votre part.
Que peut faire une clé API utilisée pour la voix ?
Uniquement ce que vous lui autorisez. Une clé contient une liste de scopes, chacun en lecture ou écriture. Une clé avec voice:write peut authentifier des appels sur un trunk ; une clé avec voice:read peut lister les enregistrements d'appels. Une clé ne peut pas accéder aux canaux ou paramètres en dehors de ses scopes.
Pourquoi un appel refusé renvoie-t-il un simple SIP 503 sans détail ?
La raison précise est inscrite sur l'enregistrement de l'appel, où vous seul pouvez la consulter. Renvoyer un 503 générique au niveau SIP empêche quiconque sonde votre trunk de découvrir quels trunks, numéros et destinations existent.
Où trouver la documentation sécurité et protection des données de Bird ?
Les certifications et la documentation de sécurité sont disponibles dans le Trust Center à trust.bird.com. L'accord de traitement des données, la déclaration de confidentialité et la politique d'utilisation acceptable sont publiés sur bird.com/legal. Pour un questionnaire fournisseur, votre équipe de compte Bird s'en charge.