Voice API FAQ

Bird Voice ermöglicht es Ihnen, Anrufe über einen SIP-Trunk an Telefonnummern zu tätigen. Ihr Telefonsystem verbindet sich mit Bird, und Bird leitet jeden Anruf über einen Carrier an das öffentliche Telefonnetz (das PSTN) weiter. Sie bringen Ihre eigene Telefonanlage oder Ihr Softphone mit; Bird übernimmt die Carrier-Strecke.

Ungefähr zehn Minuten. Erstellen Sie einen SIP-Trunk, verifizieren Sie eine Anrufer-ID, aktivieren Sie das Zielland und richten Sie Ihr Telefonsystem auf die Trunk-Adresse. Die Erstanruf-Anleitung führt Sie durch den gesamten Vorgang.

Drei Dinge auf Ihrer Seite: einen SIP-Trunk, bei dem Ihre Geräte zugelassen sind (nach IP-Bereich oder API-Key), eine verifizierte Anrufer-ID (die Nummer, die Sie als Anrufer anzeigen) und das aktivierte Zielland. Bird weist Ihrem Workspace das Routing zu – das ist die vierte Voraussetzung und geschieht auf Seiten von Bird.

Nein. Jedes SIP-fähige Telefonsystem funktioniert: ein Softphone wie Zoiper oder Linphone auf einem Laptop, eine Telefonanlage wie Asterisk oder FreeSWITCH oder ein kommerzielles System wie 3CX oder FreePBX. Bird stellt Ihnen eine SIP-Domain bereit, und Sie richten Ihre Geräte darauf aus.

Yes. You can place calls from the dashboard Phone app using WebRTC.

Pro Anruf, zu einem Tarif, der vom Zielland abhängt. Jeder Tarif hat ein Abrechnungsinkrement: eine minimale Abrechnungsdauer und danach die Schrittgröße, auf die aufgerundet wird. Ein Tarif mit einer Minute Minimum und Sechs-Sekunden-Schritten berechnet einen 10-Sekunden-Anruf für eine volle Minute.

Die abrechnungsfähige Zeit läuft ab dem Moment, in dem die angerufene Nummer abhebt, bis zum Ende des Anrufs. Klingelzeit wird nicht berechnet – ein Anruf, den niemand annimmt, kostet also nichts.

Prepaid, aus dem Wallet Ihrer Organisation. Bird prüft Ihr Guthaben, bevor der Carrier angewählt wird. Ein Anruf, den Ihr Wallet nicht decken kann, wird daher vorab mit insufficient_balance abgelehnt, statt nachträglich in Rechnung gestellt zu werden.

Ja. Pro Organisation gilt eine tägliche Ausgabenobergrenze für Voice, die zu Beginn jedes UTC-Tages zurückgesetzt wird. Wird sie überschritten, werden Anrufe mit daily_spend_exceeded abgelehnt. Die Höhe hängt von Ihrem Tarif ab, und Bird kann sie auf Anfrage erhöhen.

Öffnen Sie den Anruf im Anrufprotokoll. Die Kosten erscheinen im Datensatz, sobald er bewertet wurde – in voller Genauigkeit, ohne Steuern. Für Gesamtkosten über mehrere Anrufe exportieren Sie die gefilterte Anrufliste als CSV von der Anrufseite oder prüfen Sie Ihre Rechnungen und Nutzungsdaten.

Drei Obergrenzen: wie viele Anrufe gleichzeitig aktiv sein dürfen (gleichzeitige Anrufe), wie viele neue Anrufe Sie pro Sekunde starten dürfen (Anrufe pro Sekunde) und wie viel Sie an einem UTC-Tag für Voice ausgeben dürfen (Tagesausgaben). Jede wird pro Organisation festgelegt, und die Beträge hängen von Ihrem Plan ab.

Der Anruf wird beim Aufbau abgelehnt, noch bevor ein Carrier angewählt wird. Der Anrufdatensatz benennt das erreichte Limit: concurrent_calls_exceeded, calls_per_second_exceeded oder daily_spend_exceeded. Ihr Telefonsystem sieht ein SIP 503.

Ja. Kontaktieren Sie den Support, um eine höhere Obergrenze für gleichzeitige Anrufe oder Anrufe pro Sekunde anzufordern. Die Tagesausgaben-Obergrenze hängt von Ihrem Plan ab und kann ebenfalls erhöht werden.

Prüfen Sie, welchen Grund der Anrufdatensatz enthält. Ein Dialer kann calls_per_second_exceeded auslösen und dabei weit von der Obergrenze für gleichzeitige Anrufe entfernt sein, da die beiden Limits unabhängig voneinander sind. Verlangsamen Sie die Wählrate und versuchen Sie es erneut; ein sofortiger Wiederholungsversuch erhält dieselbe Antwort.

Ein SIP-Trunk ist die Verbindung zwischen Ihrem Telefonsystem und Bird. SIP (Session Initiation Protocol) ist die Sprache, die Telefonsysteme zum Aufbau von Anrufen verwenden, und ein Trunk ist die Leitung, über die diese Anrufe laufen. Bird stellt Ihrem Workspace eine Trunk-Adresse bereit, und Sie richten Ihr Telefonsystem darauf aus.

Die meisten Workspaces benötigen nur einen. Erstellen Sie weitere, wenn Sie separate Zugriffsregeln pro Standort oder System wünschen, da die IP-Zulassungsliste, die erlaubten API-Schlüssel und die Digest-Einstellungen jeweils pro Trunk gelten.

Die SIP-Domain des Trunks (von der Trunk-Seite kopiert), der Benutzername bird und das Passwort (das Secret eines auf dem Trunk zugelassenen API-Schlüssels). Senden Sie Anrufe an die SIP-Domain auf Port 5060 (UDP oder TCP) oder 5061 (TLS).

Ja, mit einer IP-Zulassungsliste, erlaubten API-Schlüsseln oder beidem. Fügen Sie die öffentlichen Adressen hinzu, von denen Ihre Geräte SIP senden, oder verlangen Sie, dass sich jeder Anruf mit einem API-Schlüssel per SIP Digest authentifiziert. Beides wird ab dem nächsten Anruf wirksam.

Die SIP-Domain des Trunks akzeptiert sofort keine neuen Anrufe mehr. Bereits laufende Anrufe werden fortgesetzt, und die über den Trunk erstellten Anrufdatensätze bleiben in Ihrem Anrufprotokoll.

Ihre PBX sendet den Anruf, Bird antwortet mit einer 407-Challenge, und Ihre PBX sendet den Anruf erneut mit einem Proxy-Authorization-Header, der aus dem Benutzernamen bird und dem Secret Ihres API-Schlüssels als Passwort berechnet wird. Ihre PBX sendet einen Hash des Passworts, niemals das Passwort selbst.

SHA-256 und MD5. Bird bietet standardmäßig zuerst SHA-256 und dann MD5 an, und Ihre PBX wählt den ersten unterstützten Algorithmus. Wenn Ihre Anlage nur MD5 beherrscht und eine Challenge mit führendem SHA-256 nicht korrekt verarbeitet, stellen Sie den Trunk auf „Nur MD5".

Ja. Wenn ein Trunk beides hat, wird die Quelladresse geprüft, bevor Bird zur Passwortabfrage auffordert – ein Anruf von einer nicht gelisteten Adresse wird unabhängig von den mitgesendeten Anmeldedaten abgelehnt.

Fügen Sie zuerst den neuen Schlüssel zum Trunk hinzu, stellen Sie Ihre Anlage um und widerrufen Sie dann den alten. Das Widerrufen oder Löschen eines Schlüssels entzieht ihm sofort die Authentifizierungsfähigkeit auf jedem Trunk, der ihn zugelassen hat.

Eine Anrufer-ID ist eine Telefonnummer, die Ihr Workspace als Anrufer bei ausgehenden Anrufen anzeigen darf. Bird prüft bei jedem Anruf die Rufnummer, die Ihre Anlage im SIP-From-Header setzt, gegen diese Liste – so gehen Anrufe nur unter Nummern raus, die Sie verifiziert haben.

Fügen Sie die Nummer auf der Seite „Numbers

Wenn die Versuche aufgebraucht sind, verwenden Sie „Neuen Code anfordern

Leiten Sie sie für die Minute, die die Verifizierung dauert, auf ein Telefon um, das Sie abnehmen können, und stellen Sie sie dann zurück. Bei einer Nummer, die gar keine Anrufe empfängt, kontaktieren Sie den Support.

Ab diesem Moment wird jeder Anruf, der diese Nummer präsentiert, mit caller_id_not_verified abgelehnt. Bereits laufende Anrufe werden fortgesetzt, und die Anrufprotokolle, die diese Nummer verwendet haben, bleiben unverändert.

Gebührenbetrug funktioniert, indem teure Länder angerufen werden, die Sie nie anrufen wollten. Die von Ihnen aktivierten Länder sind diejenigen, in denen Kosten anfallen können – alles andere deaktiviert zu lassen, begrenzt Ihr Risiko, falls jemand in Ihre Telefonanlage einbricht.

Finden Sie das Land auf der Destinations-Seite über das Suchfeld (Suche nach Name oder Zwei-Buchstaben-Code) und schalten Sie den Schalter ein. Die Änderung gilt ab sofort.

Anrufe in Hochrisikoländer sind teuer, und der Betreiber der angerufenen Nummer verdient einen Anteil an den Kosten. Das sind die Länder, die ein Angreifer ins Visier nimmt, wenn er in eine Telefonanlage einbricht. Lassen Sie sie deaktiviert, es sei denn, Sie haben dort Geschäftsbeziehungen, und prüfen Sie den Tarif, bevor Sie eines aktivieren.

Kontaktieren Sie den Support, um es für Ihr Konto freischalten zu lassen. „Available" bedeutet, dass Sie es aktivieren können; „Not supported" bedeutet, dass Bird derzeit von Ihrem Konto aus keine Anrufe in dieses Land vermitteln kann.

Ein verfügbares Land kann dennoch bestimmte Ziele enthalten, die das Routing noch nicht erreicht. Senden Sie die Anruf-ID an den Support, und das Routing wird entsprechend erweitert.

Zwei Header: To (die angerufene Nummer) und From (die Nummer, die Sie als Anrufer anzeigen – diese muss eine verifizierte Anrufer-ID sein). Beide müssen vollständige internationale Nummern im E.164-Format sein: ein führendes + gefolgt von Landesvorwahl und nationaler Nummer. Benutzerdefinierte Header sind nicht erforderlich.

STIR/SHAKEN ist eine Signatur, die Carrier verwenden, um zu entscheiden, ob ein Anruf ohne Kennzeichnung durchgestellt wird. Anrufe in die Vereinigten Staaten und nach Frankreich erhalten sie automatisch, ohne dass Sie etwas konfigurieren müssen. Anrufe tragen standardmäßig Level B; Level A (die stärkste Stufe) ist auf Anfrage verfügbar.

Öffnen Sie den Anruf im Anrufprotokoll. Ihr Telefonsystem sieht nur ein einfaches SIP 503, aber der genaue Grund steht im Anrufdatensatz, wo nur Sie ihn lesen können. Ein Bereich über den Details benennt die Ursache und verlinkt auf die Einstellung, mit der Sie sie beheben.

Nur wenn die Ursache behoben ist. Ein Anruf, der wegen calls_per_second_exceeded abgelehnt wurde, erhält dieselbe Antwort, bis Sie die Wählrate verlangsamen. Lesen Sie den Ablehnungsgrund, bevor Sie es erneut versuchen.

Fünf: Answered (die angerufene Nummer hat abgenommen), No answer (es hat ausgeklingelt), Failed (der Anruf wurde nicht abgeschlossen – entweder hat Bird ihn abgelehnt oder ein Carrier hat ihn nicht zugestellt), Rejected (der Carrier hat den Anruf direkt abgelehnt) und Unknown (das Ergebnis konnte nicht ermittelt werden).

Beides erscheint als Failed. Der Ablehnungsgrund macht den Unterschied: Nur eine Bird-Ablehnung enthält einen. Ein fehlgeschlagener Anruf mit Ablehnungsgrund deutet auf eine Einstellung auf Ihrer oder Birds Seite hin; einer ohne Ablehnungsgrund weist in der Regel auf die gewählte Nummer hin.

Ja. Der Tab „Live" auf der Seite Calls listet die Anrufe auf Ihren Trunks in Echtzeit, mit einer Anzahl. Ein laufender Anruf zeigt entweder Ringing (wartet darauf, dass die Gegenseite abnimmt) oder In progress (verbunden). Der Tab aktualisiert sich alle paar Sekunden.

Die Gesamtdauer läuft ab dem Moment, in dem Bird den Anruf empfangen hat, bis zum Auflegen. Die abrechenbare Zeit läuft ab der Annahme bis zum Auflegen. Die Differenz ist die Klingelzeit, in der niemand abgenommen hat – eine große Differenz ist es wert, überprüft zu werden, was Sie anrufen. Ein Anruf, den niemand beantwortet hat, kostet nichts.

Drei Wege: CSV von der Calls-Seite herunterladen (exportiert jeden Datensatz, der Ihren aktuellen Filtern entspricht, nicht nur die sichtbare Seite), über die API mit einem auf voice:read begrenzten API-Schlüssel abrufen oder die Bird CLI mit bird voice list verwenden.

Drei: voice_call.initiated (Bird hat den Anruf angenommen und das Routing gestartet), voice_call.answered (die angerufene Nummer hat abgenommen) und voice_call.ended (der Anruf ist beendet, mit dem Ergebnis). Ein unbeantworteter Anruf löst niemals das Answered-Event aus.

Ein Anruf, den Bird nach Annahme des INVITE ablehnt, endet dennoch mit voice_call.ended und trägt den Status failed sowie den sip_response_code 503. Jeder Anruf, über dessen Eröffnung Sie informiert werden, wird also auch geschlossen. Ein Anruf, den Bird überhaupt nicht zulässt (auf der SIP-Ebene abgewiesen), erzeugt keinerlei Events.

Ja. Die Zustellung ist nicht geordnet, sodass answered Sie nach ended erreichen kann. Sortieren Sie nach dem timestamp-Feld und lassen Sie ein später eintreffendes Event mit einem früheren Zeitstempel verlieren.

Deduplizieren Sie anhand des HTTP-Headers webhook-id. Bird liefert mindestens einmal zu, und das initiated-Event eines Anrufs kann mehrfach veröffentlicht werden, wenn ein Signaling-Retry es erneut sendet. Gleicher Anruf, gleiche Phase, gleiche webhook-id.

Sie befinden sich im Anrufdatensatz, nicht im Event. Ein Status failed bei voice_call.ended verrät nicht, ob Bird oder ein Carrier die Ursache war. Öffnen Sie den Anruf im Anrufprotokoll, um den Ablehnungsgrund zu sehen – die Kosten erscheinen dort, sobald der Anruf bewertet wurde.

Ein Anruf, den Bird nicht zulassen kann, wird auf SIP-Ebene abgewiesen, bevor ein Datensatz existiert. Prüfen Sie vier Dinge: Der Trunk hat einen IP-Bereich oder API-Schlüssel, der Ihre Geräte zulässt; der Anruf kam von einer Adresse auf der IP-Zulassungsliste des Trunks (hinter NAT ist das die öffentliche Adresse des Routers); die Digest-Anmeldedaten sind korrekt (Benutzername bird, das richtige API-Key-Secret, ein Algorithmus, den der Trunk anbietet); und die SIP-Domain stimmt exakt mit der Domain des Trunks überein.

Öffnen Sie den Anruf im Anrufprotokoll. Das Panel über den Details nennt die Ursache und verlinkt auf die Einstellung, die das Problem behebt. Die sieben behebbaren Gründe sind source_not_allowed, caller_id_not_verified, destination_not_enabled, insufficient_balance, daily_spend_exceeded, concurrent_calls_exceeded und calls_per_second_exceeded.

Manche Geräte verarbeiten eine Challenge, die mit SHA-256 beginnt, fehlerhaft. Setzen Sie den Digest-Algorithmus des Trunks auf „Nur MD5", und Ihre PBX erhält eine Challenge, die sie versteht.

Ihr Client befindet sich hinter NAT (einem Router oder einer Firewall, die Adressen umschreibt), und die Medien werden an eine private Adresse gesendet, die die Gegenseite nicht erreichen kann. Aktivieren Sie die NAT- oder STUN-Verarbeitung Ihres Clients, damit er seine öffentliche Adresse im Media-Offer bewirbt.

Das ist möglich. Bird unterstützt TLS auf Port 5061 für SIP-Signalisierung, sodass der Verbindungsaufbau verschlüsselt übertragen wird. UDP und TCP auf Port 5060 sind unverschlüsselt. Wählen Sie das Transportprotokoll, das Ihren Sicherheitsanforderungen entspricht.

Jedes Ereignis ist HMAC-signiert. Überprüfen Sie die Signatur mit dem Secret Ihres Endpunkts, bevor Sie auf die Payload reagieren, und rotieren Sie dieses Secret bei Bedarf über das Dashboard.

In der Region, in der Ihre Organisation gehostet wird – entweder us1 oder eu1. Ihr API-Schlüssel trägt dies in seinem Präfix (bk_us1_, bk_eu1_), wodurch die SDKs und die CLI automatisch den richtigen Endpunkt wählen, ohne dass Sie einen konfigurieren müssen.

Nur das, worauf Sie ihn beschränken. Ein Schlüssel enthält eine Liste von Berechtigungen (Scopes), jeweils mit Lese- oder Schreibzugriff. Ein Schlüssel mit voice:write kann Anrufe über einen Trunk authentifizieren; ein Schlüssel mit voice:read kann Anrufdatensätze auflisten. Ein Schlüssel kann nicht auf Kanäle oder Einstellungen außerhalb seiner Scopes zugreifen.

Der genaue Grund wird im Anrufdatensatz gespeichert, wo nur Sie ihn lesen können. Die Rückgabe eines generischen 503 auf SIP-Ebene verhindert, dass jemand, der Ihren Trunk testet, erfährt, welche Trunks, Nummern und Ziele existieren.

Zertifizierungen und Sicherheitsdokumentation finden Sie im Trust Center unter trust.bird.com. Der Datenverarbeitungsvertrag, die Datenschutzerklärung und die Nutzungsrichtlinien sind unter bird.com/legal veröffentlicht. Für einen Lieferantenfragebogen ist Ihr Bird-Account-Team zuständig.