Gesprekken starten

Je PBX stuurt een SIP-INVITE naar het SIP-domein van de trunk om een gesprek te starten. Bird controleert het verzoek, routeert het naar een telecomaanbieder en geeft de audio door. Deze pagina behandelt de vereisten, verzoekvelden, authenticatie en kosten.

Gebruik de handleiding voor het aanmaken van gesprekken om vanuit je applicatie via HTTP een gesprek te starten. Via deze route wordt na het beantwoorden een gepubliceerde Bird-sequentie uitgevoerd.

Voordat je een gesprek start

Een SIP-trunk instellen beschrijft stap voor stap de volledige configuratie van een trunk, voor beide richtingen.

Er moeten vier zaken geregeld zijn, in willekeurige volgorde. Drie daarvan stel je zelf in:

• Een trunk die je verkeer accepteert. Maak een SIP-trunk aan en schakel uitgaande gesprekken in. Voeg de IP-bereiken van je apparatuur, een toegestane API-sleutel of beide toe. Clients die geen langdurig geheim kunnen bewaren, kunnen sessiereferenties gebruiken.
• Een toegestane nummerweergave. Gebruik een Bird-nummer dat aan deze werkruimte is toegewezen, of registreer een extern nummer en rond het bijbehorende verificatiegesprek af. Als de CLI geen via Bird verkregen nummer is, garandeert verificatie niet dat de CLI over het volledige traject wordt doorgegeven of dat het gesprek tot stand komt. Zie de disclaimer over verificatie en doorgifte van de CLI.
• Het land van bestemming is ingeschakeld. Schakel de landen die je bedient in op de pagina Destinations.
• Routering is aan je werkruimte gekoppeld. Bird stelt dit voor je in en kiest welke telecomaanbieders welke bestemmingen bedienen. Zolang dit niet is ingesteld, worden gesprekken geweigerd met routing_not_configured. Dit is een van de redenen die worden behandeld bij Geweigerde gesprekken.

Wat Bird op de INVITE verwacht

Stuur het verzoek naar het SIP-domein van je trunk via een van de ondersteunde poorten. Bird leest drie onderdelen van het verzoek:

Schrijf nummers in de internationale E.164-notatie: eerst +, gevolgd door de landcode en het nationale nummer. Bird accepteert hetzelfde nummer ook met 00 in plaats van +, of als alleen cijfers beginnend met de landcode. Bird interpreteert cijfers zonder + of 00 alsof ze met een landcode beginnen. Een nummer in nationale notatie wordt daardoor niet als het bedoelde nummer geïnterpreteerd. Voeg geen technisch voorvoegsel toe aan het gebelde nummer.

Verder is dit een gewoon SIP-gesprek en hoef je geen aangepaste header mee te sturen.

Bied G.711, A-law of µ-law aan in je SDP. Verstuur toetstonen (DTMF) als RFC 4733-telefoongebeurtenissen. Bird verwijdert andere codecs, zoals G.729 of Opus, uit het aanbod dat naar de carrier gaat. Neem daarom G.711 op in elk aanbod.

Media wordt via gewoon RTP verzonden. SRTP wordt niet ondersteund. TLS op poort 5061 versleutelt de signalering, maar de audio blijft onversleuteld.

Elke oproep authenticeren

Welke stappen een oproep doorloopt, hangt af van hoe toegang tot de trunk is ingesteld:

• Alleen een IP-toelatingslijst. Eén verzoek. Bird vergelijkt het bronadres met de lijst en routeert de oproep, zonder dat er een challenge beantwoord hoeft te worden.
• Alleen toegestane API-sleutels. Bird vraagt eerst om een wachtwoord voor de oproep via de SIP Digest-uitwisseling.
• Beide. Oproepen die een toegestane API-sleutel gebruiken, moeten ook afkomstig zijn van een adres op de lijst. Ingeschakelde sessie-inloggegevens bieden de afzonderlijke toegangsroute die hieronder wordt beschreven.
• Sessie-inloggegevens ingeschakeld. Bird stuurt een challenge voor de oproep, ongeacht waar deze vandaan komt, ook vanaf een adres buiten de toelatingslijst. Die wordt beantwoord met inloggegevens die enkele minuten eerder zijn uitgegeven. Apparatuur die al via de toelatingslijst is toegelaten op een trunk zonder toegestane sleutels, blijft zonder challenge verbinding maken.

Als de trunk toegestane API-sleutels heeft, antwoordt je telefoonsysteem met een hash van het geheim van de API-sleutel, niet met het geheim zelf. Zo werkt SIP Digest-authenticatie:

1. Je PBX verstuurt de INVITE.
2. Bird antwoordt met 407 Proxy Authentication Required en één challengeregel per algoritme dat de trunk aanbiedt, standaard SHA-256 en daarna MD5.
3. Je PBX verstuurt de INVITE opnieuw met een Proxy-Authorization-header, berekend met gebruikersnaam bird en het geheim van de API-sleutel als wachtwoord.
4. Bird controleert het antwoord en gaat verder met de routering.

Een vooraf meegestuurde Proxy-Authorization-header wordt vóór de challenge verzonden. Je apparatuur moet daarom een algoritme kiezen dat de trunk aanbiedt. Bij authenticatie met een API-sleutel vereist een trunk met een IP-toelatingslijst nog steeds dat het verzoek afkomstig is van een adres op die lijst.

Bird handelt een mislukte handshake af op de SIP-laag. De poging wordt dus afgewezen voordat het platform een gespreksrecord aanmaakt. Als je gesprekken helemaal niet in het gesprekslogboek staan, controleer dan de inloggegevens in plaats van de routering.

Gespreksattestatie

Gesprekken naar de Verenigde Staten en Frankrijk krijgen een STIR/SHAKEN-attestatie. Providers gebruiken deze handtekening bij het labelen van gesprekken. Bird past standaard niveau B toe, zonder extra configuratie. Neem contact op met support om niveau A aan te vragen.

Wanneer een gesprek wordt geweigerd

Bird controleert de nummerweergave, bestemming, limieten en het walletsaldo voordat het gesprek bij een provider wordt opgezet. Je telefoonsysteem ontvangt een weigering als SIP 503; de specifieke oorzaak staat alleen in het gespreksrecord dat alleen na authenticatie toegankelijk is. Open het gesprek in het gesprekslogboek of bekijk geweigerde gesprekken voor elke reden en bijbehorende oplossing.

Verhelp de vastgelegde oorzaak voordat je het opnieuw probeert. calls_per_second_exceeded blijft bijvoorbeeld optreden totdat je minder gesprekken per seconde opzet.

Antwoorden op een gesprek dat Bird heeft vastgelegd, bevatten een X-BIRD-CALL-ID-header met de Leg ID (vcl_…) van het gesprek. Dit geldt ook voor de 503 bij een weigering met een vastgelegde reden. Haal het record op met GET /v1/voice/legs/{leg_id} of geef de ID door aan support.

Noodoproepen worden niet doorgegeven

Bird Voice geeft geen oproepen naar hulpdiensten door. Een oproep naar 112, 911, 999 of een ander alarmnummer wordt geweigerd, op elke trunk, in elk land. Je telefoonsysteem moet hulpdiensten via een andere route bereiken.

Dit gedrag is niet afhankelijk van je abonnement, saldo of bestemmingen. Configureer je telefoonsysteem om noodoproepen te routeren via een dienst die ze ondersteunt, zoals een lokale PSTN-lijn, een gateway op locatie of een andere provider. Test die route. Bird retourneert 503 voor een geweigerde noodoproep, zodat een telefoonsysteem een andere route in het kiesplan kan proberen.

Hulpdiensten zijn afhankelijk van de geregistreerde locatie van de beller, die Bird niet voor een trunk opslaat. Vertrouw niet op een route via Bird voor noodoproepen.

Kosten en facturering

Voice wordt vooraf betaald vanuit de wallet van je organisatie, net als de andere kanalen:

• De factureerbare tijd loopt van het beantwoorden tot het beëindigen van de oproep, ongeacht hoelang de telefoon daarvoor overging. Het oproeprecord toont deze tijd naast Total duration, die begint op het moment dat Bird de oproep ontving.
• Het tarief hangt af van het land van bestemming. Je tarieflijst vermeldt voor elk land de prijs in de valuta van de wallet. Een tarief bepaalt de minimale factureerbare tijd en de tijdstappen die na dat minimum gelden. Bij een tarief met een minimum van één minuut en tijdstappen van zes seconden wordt een oproep van 10 seconden bijvoorbeeld als één minuut gefactureerd.
• De wallet wordt gecontroleerd voordat de oproep naar de provider wordt opgezet. Als je saldo niet toereikend is, wordt de oproep vooraf geweigerd met insufficient_balance in plaats van achteraf gefactureerd. Houd een buffer aan of schakel automatisch opwaarderen in.
• Er geldt een dagelijkse bestedingslimiet voor Voice. Zodra die is overschreden, worden oproepen geweigerd met daily_spend_exceeded totdat de volgende UTC-dag begint. Voor een werkruimte kun je onder Voice > Destinations ook een dagelijkse limiet per land van bestemming instellen. Een oproep moet binnen beide limieten passen. Het bedrag hangt af van je abonnement.
• De kosten verschijnen bij de oproep zodra ze zijn berekend, met volledige precisie en exclusief belasting.

Gebruik Gebruik, uitgaven en facturen om de kosten van meerdere oproepen te bekijken. De CSV-export Legs bevat de gespreksduur en factureerbare tijd, maar heeft geen kostenkolom.

Volgende stappen