Voice API FAQ

Met Bird Voice kunt u bellen naar telefoonnummers via een SIP-trunk. Uw telefoonsysteem maakt verbinding met Bird, en Bird routeert elk gesprek via een carrier naar het openbare telefoonnetwerk (het PSTN). U brengt uw eigen PBX of softphone mee; Bird regelt het carriertraject.

Ongeveer tien minuten. Maak een SIP-trunk aan, verifieer een beller-ID, schakel het bestemmingsland in en wijs uw telefoonsysteem naar het trunk-adres. De eerste-gesprekgids begeleidt u door het hele proces.

Drie dingen aan uw kant: een SIP-trunk waarop uw apparatuur is toegestaan (op basis van IP-bereik of API-key), een geverifieerd beller-ID (het nummer dat u als beller presenteert), en het bestemmingsland ingeschakeld. Bird koppelt routering aan uw workspace — dat is de vierde voorwaarde en wordt aan de kant van Bird geregeld.

Nee. Elk SIP-compatibel telefoonsysteem werkt: een softphone zoals Zoiper of Linphone op een laptop, een PBX zoals Asterisk of FreeSWITCH, of een commercieel systeem zoals 3CX of FreePBX. Bird geeft u een SIP-domein en u wijst uw apparatuur daarnaartoe.

Ja. U kunt bellen vanuit de Phone-app in het dashboard met behulp van WebRTC.

Per gesprek, tegen een tarief dat afhangt van het bestemmingsland. Elk tarief heeft een factureringsinterval: een minimaal gefactureerde tijd, gevolgd door de stap waarnaar daarna wordt afgerond. Een tarief met een minimum van één minuut en stappen van zes seconden brengt een gesprek van 10 seconden in rekening als een volledige minuut.

Factureerbare tijd loopt vanaf het moment dat het gebelde nummer opneemt tot het moment dat het gesprek eindigt. Beltijd wordt niet gefactureerd, dus een gesprek dat niemand beantwoordt kost niets.

Prepaid, vanuit de wallet van uw organisatie. Bird controleert uw saldo voordat de carrier wordt gebeld, dus een gesprek dat uw wallet niet kan dekken wordt vooraf geweigerd met insufficient_balance in plaats van achteraf gefactureerd.

Ja. Per organisatie geldt een dagelijks bestedingsplafond voor spraak, dat aan het begin van elke UTC-dag wordt gereset. Daarboven worden gesprekken geweigerd met daily_spend_exceeded. Het bedrag hangt af van uw plan en Bird kan het op verzoek verhogen.

Open het gesprek in het gesprekslogboek. De kosten verschijnen op het record zodra het is beoordeeld, met volledige precisie en exclusief belasting. Voor totalen over meerdere gesprekken exporteert u de gefilterde gesprekslijst als CSV vanaf de Calls-pagina, of raadpleegt u uw facturen en verbruik.

Drie plafonds: hoeveel gesprekken u tegelijkertijd mag voeren (gelijktijdige gesprekken), hoeveel nieuwe gesprekken u per seconde mag starten (gesprekken per seconde), en hoeveel u per UTC-dag aan voice mag besteden (dagelijkse besteding). Elk wordt per organisatie ingesteld en de bedragen hangen af van uw abonnement.

Het gesprek wordt geweigerd bij het opzetten, nog vóór een carrier wordt gebeld. Het gespreksrecord vermeldt welke limiet is bereikt: concurrent_calls_exceeded, calls_per_second_exceeded of daily_spend_exceeded. Uw telefoonsysteem ziet een SIP 503.

Ja. Neem contact op met support om een hoger plafond voor gelijktijdige gesprekken of gesprekken per seconde aan te vragen. Het dagelijkse bestedingsplafond hangt af van uw abonnement en kan ook worden verhoogd.

Controleer welke reden het gespreksrecord bevat. Een dialer kan calls_per_second_exceeded bereiken terwijl het plafond voor gelijktijdige gesprekken lang niet in zicht is, omdat de twee limieten onafhankelijk zijn. Verlaag de belsnelheid en probeer opnieuw; direct opnieuw proberen levert hetzelfde antwoord op.

Een SIP-trunk is de verbinding tussen uw telefoonsysteem en Bird. SIP (Session Initiation Protocol) is de taal die telefoonsystemen spreken om gesprekken op te zetten, en een trunk is de lijn waarover die gesprekken lopen. Bird kent uw workspace een trunk-adres toe en u wijst uw telefoonsysteem daarnaar.

De meeste workspaces hebben er maar één nodig. Maak er meer aan wanneer u aparte toegangsregels per locatie of per systeem wilt, aangezien de IP-allowlist, de toegestane API-sleutels en de Digest-instellingen allemaal per trunk gelden.

Het SIP-domein van de trunk (gekopieerd van de trunkpagina), de gebruikersnaam bird en het wachtwoord (het geheim van een API-sleutel die is toegestaan op de trunk). Stuur oproepen naar het SIP-domein op poort 5060 (UDP of TCP) of 5061 (TLS).

Ja, met een IP-allowlist, toegestane API-sleutels of beide. Voeg de publieke adressen toe van waaruit uw apparatuur SIP verstuurt, of vereis dat elk gesprek zich authenticeert met een API-sleutel via SIP Digest. Beide worden van kracht bij het volgende gesprek.

Het SIP-domein van de trunk accepteert onmiddellijk geen nieuwe gesprekken meer. Lopende gesprekken gaan door en de gespreksrecords die via de trunk zijn gemaakt, blijven in uw gesprekslogboek.

Uw PBX verstuurt het gesprek, Bird antwoordt met een 407-challenge en uw PBX verstuurt het gesprek opnieuw met een Proxy-Authorization-header die is berekend op basis van gebruikersnaam bird en het geheim van uw API-sleutel als wachtwoord. Uw PBX verstuurt een hash van het wachtwoord, nooit het wachtwoord zelf.

SHA-256 en MD5. Bird biedt standaard eerst SHA-256 en daarna MD5 aan, en uw PBX kiest het eerste dat het ondersteunt. Als uw apparatuur alleen MD5 aankan en een challenge die begint met SHA-256 niet correct verwerkt, stel de trunk dan in op alleen MD5.

Ja. Wanneer een trunk beide heeft, wordt het bronadres gecontroleerd voordat Bird om een wachtwoord vraagt, dus een gesprek vanaf een niet-vermeld adres wordt geweigerd ongeacht de meegestuurde inloggegevens.

Voeg eerst de nieuwe sleutel toe aan de trunk, schakel uw apparatuur over en trek daarna de oude in. Het intrekken of verwijderen van een sleutel verwijdert onmiddellijk de mogelijkheid om te authenticeren op elke trunk die de sleutel toestond.

Een beller-ID is een telefoonnummer dat uw workspace mag presenteren als beller bij uitgaande gesprekken. Bird controleert bij elk gesprek het bellende nummer dat uw apparatuur in de SIP From-header plaatst tegen deze lijst, zodat gesprekken alleen uitgaan onder nummers die u hebt geverifieerd.

Voeg het nummer toe op de pagina Nummers in E.164-formaat. Bird plaatst onmiddellijk een verificatieoproep naar het nummer. Beantwoord de oproep, luister naar een zescijferige code en voer deze in op het dashboard. U krijgt vijf pogingen en het nummer wordt bruikbaar zodra één poging is geaccepteerd.

Als de pogingen op zijn, gebruik dan Nieuwe code ophalen in de rij van het nummer voor een nieuwe verificatieoproep. Als het nummer nog wacht op de code, verwijder dan het beller-ID en voeg het nummer opnieuw toe.

Leid het door naar een telefoon die u kunt opnemen gedurende de minuut die de verificatie duurt, en zet het daarna terug. Neem voor een nummer dat helemaal geen gesprekken ontvangt contact op met support.

Vanaf dat moment wordt elk gesprek dat dat nummer presenteert geweigerd met caller_id_not_verified. Gesprekken die al bezig zijn gaan door, en de gespreksrecords die het nummer gebruikten blijven zoals ze zijn.

Tolfraude werkt door dure landen te bellen die u nooit van plan was te bellen. De landen die u inschakelt zijn de landen waarin u kosten kunt oplopen, dus alles uitgeschakeld laten beperkt uw risico als iemand inbreekt in uw telefoonsysteem.

Zoek het land op de pagina Destinations met behulp van het zoekveld (zoekt op naam of tweeletterige code) en zet de schakelaar aan. De wijziging geldt vanaf dat moment.

Gesprekken naar landen met hoog risico zijn duur, en degene die het nummer beheert dat u belt, ontvangt een deel van de kosten. Dit zijn de landen die een aanvaller als doelwit kiest als ze inbreken in een telefoonsysteem. Laat ze uitgeschakeld tenzij u er zakelijk actief bent, en controleer het tarief voordat u er een inschakelt.

Neem contact op met support om het voor uw account te laten openen. Available betekent dat u het kunt inschakelen; Not supported betekent dat Bird momenteel geen gesprekken naar dat land kan plaatsen vanaf uw account.

Een beschikbaar land kan nog steeds specifieke bestemmingen bevatten die de routering nog niet bereikt. Stuur het gesprek-ID naar support en zij zullen de routering uitbreiden om het te dekken.

Twee headers: To (het nummer dat wordt gebeld) en From (het nummer dat u als beller presenteert, wat een geverifieerd beller-ID moet zijn). Beide moeten volledige internationale nummers zijn in E.164-formaat: een + gevolgd door de landcode en het nationale nummer. Er zijn geen aangepaste headers nodig.

STIR/SHAKEN is een handtekening die carriers gebruiken bij het beslissen of ze een gesprek ongelabeld doorlaten. Gesprekken naar de Verenigde Staten en Frankrijk dragen dit automatisch mee, zonder dat u iets hoeft te configureren. Gesprekken dragen standaard niveau B; niveau A (het sterkste) is op aanvraag beschikbaar.

Open het gesprek in het gesprekslogboek. Uw telefoonsysteem ziet een eenvoudige SIP 503, maar de specifieke reden staat op het gespreksrecord waar alleen u het kunt lezen. Een paneel boven de details vermeldt de oorzaak en linkt naar de instelling om het op te lossen.

Pas als de oorzaak is opgelost. Een gesprek dat is geweigerd vanwege calls_per_second_exceeded krijgt hetzelfde antwoord totdat u de belsnelheid verlaagt. Lees de weigeringsreden voordat u het opnieuw probeert.

Vijf: Answered (het gebelde nummer nam op), No answer (het rinkelde zonder antwoord), Failed (het gesprek is niet voltooid, Bird heeft het geweigerd of een carrier heeft het laten mislukken), Rejected (de carrier heeft het gesprek direct afgewezen) en Unknown (de uitkomst kon niet worden vastgesteld).

Beide verschijnen als Failed. De weigeringsreden maakt het verschil: alleen een weigering door Bird bevat er een. Een mislukt gesprek met een weigeringsreden wijst op een instelling aan uw kant of die van Bird; een gesprek zonder weigeringsreden wijst meestal op het nummer dat u hebt gebeld.

Ja. Het tabblad Live op de pagina Calls toont de gesprekken op uw trunks op dit moment, met een telling. Een lopend gesprek wordt weergegeven als Ringing (wacht tot de andere kant opneemt) of In progress (verbonden). Het tabblad ververst elke paar seconden.

De totale duur loopt vanaf het moment dat Bird het gesprek ontving tot het ophangen. De factureerbare tijd loopt van het opnemen tot het ophangen. Het verschil is de beltijd waarin niemand opnam, dus een groot verschil is het waard om te bekijken wat u belt. Een gesprek dat niemand beantwoordt, kost niets.

Op drie manieren: download CSV vanaf de pagina Calls (exporteert elk record dat overeenkomt met uw huidige filters, niet alleen de zichtbare pagina), lees ze uit via de API met een API-sleutel met scope voice:read, of gebruik de Bird CLI met bird voice list.

Drie: voice_call.initiated (Bird heeft het gesprek geaccepteerd en is begonnen met routeren), voice_call.answered (het gebelde nummer nam op), en voice_call.ended (het gesprek is afgelopen, met de uitkomst). Een onbeantwoord gesprek genereert nooit het answered-event.

Een gesprek dat Bird weigert na het accepteren van de INVITE eindigt nog steeds met voice_call.ended, met status failed en sip_response_code 503. Elk gesprek waarvan u hoort dat het geopend is, wordt dus ook afgesloten. Een gesprek dat Bird helemaal niet kan toelaten (afgewezen op de SIP-laag) genereert geen enkel event.

Ja. Afleveringen zijn niet geordend, dus answered kan na ended bij u aankomen. Sorteer op het timestamp-veld en laat een later aangekomen event met een eerder tijdstempel verliezen.

Dedupliceer op de webhook-id HTTP-header. Bird levert minstens één keer af, en het initiated-event van een gesprek kan meer dan eens worden gepubliceerd wanneer een signalerings-retry het opnieuw afspeelt. Zelfde gesprek, zelfde fase, zelfde webhook-id.

Die staan op het gespreksrecord, niet in het event. Een failed-status op voice_call.ended vertelt u niet of Bird of een carrier de oorzaak was. Open het gesprek in het gesprekslogboek voor de weigeringsreden; de kosten verschijnen daar zodra het gesprek is getarifeerd.

Een gesprek dat Bird niet kan toelaten, wordt op de SIP-laag afgewezen voordat er een record bestaat. Controleer vier dingen: de trunk heeft een IP-bereik of API-sleutel die uw apparatuur toestaat, het gesprek is binnengekomen vanaf een adres op de IP-allowlist van de trunk (achter NAT is dat het publieke adres van de router), de Digest-referenties zijn correct (gebruikersnaam bird, het juiste API-sleutelgeheim, een algoritme dat de trunk aanbiedt) en het SIP-domein komt exact overeen met het domein van de trunk.

Open het gesprek in het gesprekslogboek. Het paneel boven de details noemt de oorzaak en linkt naar de instelling die het oplost. De zeven redenen die u kunt verhelpen zijn source_not_allowed, caller_id_not_verified, destination_not_enabled, insufficient_balance, daily_spend_exceeded, concurrent_calls_exceeded en calls_per_second_exceeded.

Sommige apparatuur gaat niet goed om met een challenge die begint met SHA-256. Stel het Digest-algoritme van de trunk in op alleen MD5, dan krijgt uw PBX een challenge die het begrijpt.

Uw client zit achter NAT (een router of firewall die adressen herschrijft) en de media gaat naar een privéadres dat de andere kant niet kan bereiken. Schakel de NAT- of STUN-afhandeling van uw client in, zodat deze zijn publieke adres adverteert in het media-aanbod.

Dat kan. Bird ondersteunt TLS op poort 5061 voor SIP-signalering, waardoor de gespreksopbouw versleuteld is tijdens verzending. UDP en TCP op poort 5060 zijn onversleuteld. Kies het transport dat past bij uw beveiligingseisen.

Elk event wordt HMAC-ondertekend. Verifieer de handtekening met het geheim van uw endpoint voordat u actie onderneemt op de payload, en roteer dat geheim vanuit het dashboard wanneer u dat nodig acht.

In de regio waar uw organisatie wordt gehost, ofwel us1 of eu1. Uw API-sleutel draagt dit in het prefix (bk_us1_, bk_eu1_), waardoor de SDK's en de CLI automatisch het juiste endpoint kiezen zonder dat u er een hoeft te configureren.

Alleen waarvoor u hem scopet. Een sleutel bevat een lijst met scopes, elk op read of write. Een sleutel met voice:write kan gesprekken op een trunk authenticeren; een sleutel met voice:read kan gespreksrecords opvragen. Een sleutel heeft geen toegang tot kanalen of instellingen buiten zijn scopes.

De specifieke reden wordt vastgelegd in het gespreksrecord, waar alleen u het kunt lezen. Door een generieke 503 naar de SIP-laag te sturen, voorkomt u dat iemand die uw trunk aftast, te weten komt welke trunks, nummers en bestemmingen er bestaan.

Certificeringen en beveiligingsdocumentatie staan in het Trust Center op trust.bird.com. De gegevensverwerkingsovereenkomst, privacyverklaring en het beleid voor acceptabel gebruik zijn gepubliceerd op bird.com/legal. Voor een leveranciersvragenlijst helpt uw Bird-accountteam u verder.