Trunks SIP
Un trunk SIP relie votre système téléphonique à Bird. Il fournit à votre PBX, l'autocommutateur qui achemine vos appels, une adresse pour les appels sortants, définit comment Bird les authentifie, et peut aussi recevoir les appels arrivant sur les numéros que vous détenez. Configurez les trunks sous Voice > Trunks SIP.
La plupart des configurations n'ont besoin que d'un seul trunk. Créez des trunks distincts lorsque des sites ou des systèmes nécessitent des listes d'adresses IP autorisées, des clés API, des paramètres d'identifiants de session ou des algorithmes Digest différents.
Créer un trunk
Sélectionnez Create trunk et saisissez un nom. Vous pouvez modifier ce libellé du tableau de bord ultérieurement ; il n'est pas transmis avec les appels.
Bird attribue un domaine SIP fixe au trunk. Saisissez ce domaine dans votre système téléphonique pour que Bird puisse associer les appels au trunk.
Un nouveau trunk refuse tous les appels tant que vous n'avez pas indiqué qui peut les passer : une plage IP, une clé API, des identifiants de session ou une combinaison.
Direction des appels
Un trunk transporte chaque direction séparément, et un nouveau trunk n'en transporte aucune. La page du trunk comporte une section par direction, et une direction désactivée n'affiche que la commande permettant de l'activer.
Les appels sortants correspondent à votre PBX passant des appels via Bird. Sélectionnez Enable outbound. Tant que cette option n'est pas activée, le trunk refuse toute tentative sortante quels que soient ses identifiants. Les informations de connexion du trunk, les listes d'adresses autorisées, les clés, les identifiants de session et l'offre Digest se trouvent tous dans cette section, car ils régissent ce qui peut se connecter.
Les appels entrants correspondent à Bird acheminant les appels vers votre PBX, pour les numéros auxquels ce trunk répond. Sélectionnez Enable inbound, puis ajoutez au moins une passerelle de livraison : un trunk sans passerelle refuse tous les appels entrants vers ses numéros. La liste Inbound numbers de la section indique lesquels de vos numéros envoient leurs appels ici.
L'association d'un numéro au trunk se fait sur le numéro, pas ici. Consultez Réception des appels pour cela, ainsi que pour le rôle des formats de numéro d'une passerelle.
Warning: turning inbound calling off puts every number pointing at this trunk back on reject, and turning it back on does not restore them. Deleting the trunk does the same.
Informations de connexion
Ouvrez un trunk pour voir ce que vous devez saisir dans votre PBX :
| Paramètre | Valeur |
|---|---|
| Domaine SIP | Le domaine propre au trunk. Copiez-le intégralement depuis la page du trunk |
| Nom d'utilisateur | Toujours bird |
| Mot de passe | Le secret d'une clé API autorisée sur ce trunk (voir Authentification par clé API) |
Note: with the IP allow list alone, the SIP domain and a port are all you need: the username and password are for API key authentication. A client holding a session credential uses the password from that credential instead.
Envoyez vos appels au domaine SIP sur l'un de ces ports :
| Transport | Port | Remarques |
|---|---|---|
| UDP | 5060 | Le port par défaut supposé par la plupart des équipements |
| TCP | 5060 | Même port que UDP, choisissez donc le transport sur votre PBX |
| TLS | 5061 | SIP sur TLS, pour la signalisation que vous souhaitez chiffrer en transit |
Contrôler qui peut envoyer des appels
Un trunk peut authentifier les équipements par adresse IP source, clé API ou identifiant de session à durée de vie courte. Activez les méthodes dont vos clients ont besoin.
Configurez-les dans IP allow list, Allowed API keys et Session credentials. Les modifications enregistrées s'appliquent aux nouveaux appels.
Liste d'adresses IP autorisées
Ajoutez les adresses publiques depuis lesquelles votre équipement envoie du SIP, sous forme d'adresses uniques ou de plages CIDR, chacune avec une description facultative. Le filtrage IP devient actif dès que la liste contient une entrée : à partir de ce moment, seules les plages listées peuvent envoyer des appels à ce trunk.
Ajoutez l'adresse source publique qui atteint Bird. Pour un équipement derrière un NAT, utilisez l'adresse publique du routeur au lieu de l'adresse privée du système téléphonique. Bird refuse les appels provenant d'adresses non listées au niveau de la couche SIP, ils n'apparaissent donc généralement pas dans le journal des appels. Consultez le dépannage voix pour les appels manquants.
Authentification par clé API
Bird peut aussi (ou à la place) demander un mot de passe pour chaque appel. L'échange repose sur l'authentification Digest SIP : Bird envoie un défi, votre système téléphonique répond avec un hachage du mot de passe plutôt que le mot de passe lui-même, et Bird le vérifie par rapport à une clé Bird API.
- Attribuez à une clé API la permission voice au niveau write, qui est le niveau contre lequel un trunk s'authentifie. Ajoutez-la à une clé que vous possédez déjà ou créez-en une nouvelle. Dans les deux cas, le secret de la clé fonctionne sans modification : une clé déjà déployée conserve le secret avec lequel vos systèmes sont configurés, et une nouvelle clé affiche son secret une seule fois, à la création, alors enregistrez-le à ce moment-là. Voir Clés API.
- Sur la page du trunk, sous Allowed API keys, ajoutez cette clé.
- Dans votre PBX, définissez le nom d'utilisateur sur bird et le mot de passe sur le secret de la clé.
L'authentification par clé API devient active dès que la liste contient une clé : à partir de ce moment, seules les clés que vous listez peuvent s'authentifier.
Retirer la permission voice d'une clé l'empêche immédiatement de s'authentifier, mais le trunk la conserve dans la liste autorisée. Réattribuez la permission et le trunk fonctionne à nouveau avec le même secret, sans rien modifier sur le trunk ni dans votre PBX. Tant que la permission est absente, la page du trunk signale cette clé pour que la liste autorisée ne semble jamais fonctionnelle alors qu'elle ne l'est pas.
Révoquer ou supprimer une clé API supprime immédiatement sa capacité d'authentification, sur tous les trunks qui l'autorisaient, et cette suppression est définitive. Pour effectuer une rotation, ajoutez d'abord la nouvelle clé au trunk, basculez votre équipement, puis révoquez l'ancienne.
Identifiants de session
Un identifiant de session est un nom d'utilisateur et un mot de passe SIP à durée de vie courte. Il répond au même défi Digest qu'une clé API sans exposer un secret à longue durée de vie.
Activez-les sous Session credentials sur la page du trunk ; ils sont désactivés sur un nouveau trunk. Ce qu'ils admettent :
- Le téléphone du tableau de bord, qui en génère un par appel pour vous.
- Un client SIP piloté par le CLI : bird voice tools test-call en génère un pour l'appel qu'il passe, et bird voice session-credentials create en génère un à coller dans tout autre client. Les deux nécessitent un accès voice au niveau write.
Un identifiant appartient à l'espace de travail plutôt qu'à un seul trunk, un client peut donc l'utiliser sur tous les trunks éligibles. Le client doit présenter l'identifiant, et le trunk doit avoir les identifiants de session activés. Bird ne renvoie le mot de passe qu'au moment de sa génération.
Les activer ne change pas la façon dont les équipements de la liste d'adresses IP autorisées se connectent : un appel provenant d'une adresse listée, sur un trunk sans clés API autorisées, est toujours admis sans demande de mot de passe.
Algorithme Digest
Par défaut, Bird propose SHA-256 en premier et MD5 en second. Votre PBX répond avec le premier algorithme qu'il prend en charge.
Modifiez l'offre sous Digest algorithm lorsque votre équipement l'exige. Pour un PBX qui gère mal un défi commençant par SHA-256, sélectionnez MD5 only. Un trunk n'accepte que les algorithmes qu'il propose. Les clés API fonctionnent avec l'un ou l'autre algorithme et n'ont pas besoin d'être réémises.
Conservez MD5 dans l'offre sur tout trunk depuis lequel vous appelez avec le téléphone : un navigateur répond avec MD5 et rien d'autre, un trunk proposant uniquement SHA-256 refuse donc tous les appels depuis le navigateur.
Supprimer un trunk
La suppression d'un trunk prend effet immédiatement : son domaine SIP cesse d'accepter les nouveaux appels, et chaque numéro qui y était associé recommence à rejeter les 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.
Étapes suivantes
| Page | Contenu |
|---|---|
| Passez votre premier appel | D'un espace de travail vide à un téléphone qui sonne |
| Téléphone | Appeler depuis le tableau de bord, via un trunk acceptant les identifiants de session |
| Passer des appels | Ce que Bird attend sur le INVITE, et ce que coûte un appel |
| Recevoir des appels | Associer un numéro à ce trunk et ses passerelles de livraison |
| Identifiants d'appelant | Enregistrer un numéro et prouver que vous le possédez avec un appel de vérification |
| Clés API | Créer une clé, choisir ses portées et effectuer sa rotation |
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