Anrufe tätigen

Ihre PBX sendet ein SIP-INVITE an die SIP-Domain des Trunks, um einen Anruf zu tätigen. Bird prüft die Anfrage, leitet sie an einen Netzbetreiber weiter und überträgt die Audiodaten. Diese Seite behandelt die Voraussetzungen, Anfragefelder, Authentifizierung und Kosten.

Um einen Anruf aus Ihrer Anwendung über HTTP zu starten, verwenden Sie den Leitfaden zum Erstellen von Anrufen. Bei diesem Verfahren wird nach der Anrufannahme eine veröffentlichte Bird-Sequenz ausgeführt.

Bevor Sie einen Anruf tätigen

Einen SIP-Trunk einrichten führt Schritt für Schritt durch die vollständige Einrichtung eines Trunks für beide Richtungen.

Vier Voraussetzungen müssen erfüllt sein. Die Reihenfolge ist beliebig, und drei davon richten Sie selbst ein:

• Ein Trunk, der Ihren Datenverkehr akzeptiert. Erstellen Sie einen SIP-Trunk und aktivieren Sie ausgehende Anrufe. Fügen Sie die IP-Bereiche Ihrer Geräte, einen zugelassenen API-Schlüssel oder beides hinzu. Clients, die kein langlebiges Geheimnis speichern können, können einen Sitzungszugangsnachweis verwenden.
• Eine zulässige Anrufer-ID. Verwenden Sie eine Bird-Nummer, die diesem Workspace zugewiesen ist, oder registrieren Sie eine externe Nummer und führen Sie den zugehörigen Verifizierungsanruf durch. Die Verifizierung garantiert weder die durchgängige Übermittlung der CLI noch den Verbindungsaufbau, wenn die CLI keine über Bird bezogene Nummer ist: siehe den Haftungsausschluss zur Verifizierung und Übermittlung der CLI.
• Das Zielland ist aktiviert. Aktivieren Sie auf der Seite Destinations die Länder, die Sie bedienen.
• Das Routing ist Ihrem Workspace zugeordnet. Bird richtet dies für Sie ein und legt fest, welche Netzbetreiber welche Ziele bedienen. Bis das Routing eingerichtet ist, werden Anrufe mit routing_not_configured abgelehnt. Dies ist einer der unter Abgelehnte Anrufe beschriebenen Gründe.

Was Bird im INVITE erwartet

Senden Sie die Anfrage an die SIP-Domain Ihres Trunks über einen der unterstützten Ports. Bird liest drei Teile der Anfrage aus:

Schreiben Sie Nummern im internationalen E.164-Format: ein führendes +, gefolgt von der Landesvorwahl und der nationalen Nummer. Bird akzeptiert dieselbe Nummer auch mit 00 statt + oder als reine Ziffernfolge, die mit der Landesvorwahl beginnt. Bird interpretiert Ziffernfolgen ohne + oder 00 so, dass sie mit einer Landesvorwahl beginnen. Eine Nummer im nationalen Format wird daher nicht als die von Ihnen gemeinte Nummer erkannt. Fügen Sie der angerufenen Nummer kein technisches Präfix hinzu.

Abgesehen von diesen Vorgaben handelt es sich um einen gewöhnlichen SIP-Anruf. Sie müssen keine benutzerdefinierten Header senden.

Bieten Sie in Ihrem SDP G.711 mit A-law oder µ-law an. Senden Sie Tastentöne (DTMF) als Telefonereignisse gemäß RFC 4733. Bird entfernt andere Codecs wie G.729 oder Opus aus dem Angebot, das an den Netzbetreiber gesendet wird. Nehmen Sie deshalb G.711 in jedes Angebot auf.

Die Medienübertragung erfolgt über unverschlüsseltes RTP. SRTP wird nicht unterstützt. TLS auf Port 5061 verschlüsselt die Signalisierung, die Audiodaten bleiben unverschlüsselt.

Authentifizierung jedes Anrufs

Welche Schritte ein Anruf durchläuft, hängt davon ab, wie der Trunk den Zugang erlaubt:

• Nur IP-Zulassungsliste. Eine einzige Anfrage genügt. Bird gleicht die Quelladresse mit der Liste ab und leitet den Anruf weiter, ohne eine Authentifizierungsaufforderung zu senden.
• Nur zugelassene API-Schlüssel. Bird fordert für den Anruf zunächst ein Passwort über das SIP-Digest-Verfahren an.
• Beides. Anrufe mit einem zugelassenen API-Schlüssel müssen auch von einer aufgeführten Adresse stammen. Aktivierte Sitzungszugangsdaten ermöglichen den unten beschriebenen separaten Zugangsweg.
• Sitzungszugangsdaten aktiviert. Bird sendet für den Anruf unabhängig von seiner Herkunft eine Authentifizierungsaufforderung, auch wenn die Adresse nicht auf der Zulassungsliste steht. Die Antwort erfolgt mit Zugangsdaten, die wenige Minuten zuvor ausgestellt wurden. Geräte, die bereits über die Zulassungsliste eines Trunks ohne zugelassene Schlüssel Zugang haben, verbinden sich weiterhin ohne Authentifizierungsaufforderung.

Wenn für den Trunk API-Schlüssel zugelassen sind, antwortet Ihre Telefonanlage mit einem Hash des geheimen Werts des API-Schlüssels statt mit dem geheimen Wert selbst. So funktioniert die SIP-Digest-Authentifizierung:

1. Ihre PBX sendet das INVITE.
2. Bird antwortet mit 407 Proxy Authentication Required und einer Zeile zur Authentifizierungsaufforderung für jeden vom Trunk angebotenen Algorithmus. Standardmäßig ist die Reihenfolge SHA-256, dann MD5.
3. Ihre PBX sendet das INVITE erneut mit einem Proxy-Authorization-Header, der mit dem Benutzernamen bird und dem geheimen Wert des API-Schlüssels als Passwort berechnet wird.
4. Bird prüft die Antwort und setzt das Routing fort.

Ein vorab gesendeter Proxy-Authorization-Header wird vor der Authentifizierungsaufforderung übermittelt. Ihre Anlage muss daher einen Algorithmus wählen, den der Trunk anbietet. Bei der Authentifizierung mit einem API-Schlüssel muss die Anfrage bei einem Trunk mit IP-Zulassungsliste weiterhin von einer aufgeführten Adresse stammen.

Bird beantwortet einen fehlgeschlagenen Handshake auf der SIP-Ebene. Der Versuch wird also abgewiesen, bevor die Plattform einen Anrufdatensatz erstellt. Wenn Ihre Anrufe im Anrufprotokoll vollständig fehlen, prüfen Sie die Zugangsdaten statt des Routings.

Anrufattestierung

Anrufe in die USA und nach Frankreich erhalten eine STIR/SHAKEN-Attestierung. Netzbetreiber verwenden diese Signatur bei der Kennzeichnung von Anrufen. Bird wendet standardmäßig Stufe B an, ohne dass eine zusätzliche Konfiguration nötig ist. Wenden Sie sich an den Support, um Stufe A anzufordern.

Wenn ein Anruf abgelehnt wird

Bird prüft die Anrufer-ID, das Ziel, die Limits und das Wallet-Guthaben, bevor ein Netzbetreiber angewählt wird. Eine Ablehnung erreicht Ihre Telefonanlage als SIP 503; die konkrete Ursache bleibt im authentifizierten Anrufdatensatz. Öffnen Sie den Anruf im Anrufprotokoll, oder sehen Sie unter Abgelehnte Anrufe die einzelnen Gründe und Lösungen nach.

Beheben Sie die protokollierte Ursache, bevor Sie es erneut versuchen. Beispielsweise tritt calls_per_second_exceeded weiterhin auf, bis Sie die Wählrate senken.

Antworten auf einen von Bird protokollierten Anruf enthalten einen X-BIRD-CALL-ID-Header mit der Leg ID (vcl_…) des Anrufs. Das gilt auch für die Antwort 503 bei einer Ablehnung mit protokolliertem Grund. Rufen Sie den Datensatz mit GET /v1/voice/legs/{leg_id} ab, oder geben Sie die ID beim Support an.

Notrufe werden nicht weitergeleitet

Bird Voice leitet keine Anrufe an Notdienste weiter. Ein Anruf an 112, 911, 999 oder eine andere Notrufnummer wird auf jedem Trunk in jedem Land abgelehnt. Ihre Telefonanlage muss Notdienste über einen anderen Weg erreichen.

Dieses Verhalten hängt nicht von Ihrem Tarif, Ihrem Guthaben oder Ihren Zielen ab. Konfigurieren Sie Ihre Telefonanlage so, dass sie Notrufe über einen Dienst weiterleitet, der diese unterstützt, etwa einen lokalen PSTN-Anschluss, ein Gateway vor Ort oder einen anderen Anbieter. Testen Sie diesen Weg. Bird gibt bei einem abgelehnten Notruf 503 zurück. So kann eine Telefonanlage einen anderen im Wählplan hinterlegten Weg versuchen.

Notdienste sind auf den registrierten Standort des Anrufers angewiesen, den Bird für einen Trunk nicht speichert. Verlassen Sie sich bei Notrufen nicht auf eine Route über Bird.

Kosten und Abrechnung

Voice wird wie die anderen Kanäle im Voraus aus dem Wallet Ihrer Organisation bezahlt:

• Die abrechenbare Zeit läuft von der Annahme bis zum Ende des Anrufs, unabhängig davon, wie lange es zuvor geklingelt hat. Der Anrufdatensatz zeigt sie neben Total duration an. Diese Gesamtdauer beginnt, sobald Bird den Anruf empfangen hat.
• Der Tarif hängt vom Zielland ab. Ihre Tarifübersicht gibt den Preis für jedes Land in der Währung des Wallets an. Ein Tarif legt eine Mindestabrechnungsdauer und die anschließende Taktung fest. Ein Tarif mit einer Minute Mindestabrechnungsdauer und einer Taktung von sechs Sekunden rechnet beispielsweise einen 10-sekündigen Anruf als eine Minute ab.
• Das Wallet wird geprüft, bevor der Netzbetreiber angewählt wird. Reicht Ihr Guthaben für einen Anruf nicht aus, wird dieser vorab mit insufficient_balance abgelehnt, statt Ihnen nachträglich berechnet zu werden. Halten Sie eine Guthabenreserve vor oder aktivieren Sie automatische Aufladungen.
• Für Voice gilt ein tägliches Ausgabenlimit. Nach dessen Überschreitung werden Anrufe mit daily_spend_exceeded abgelehnt, bis der nächste UTC-Tag beginnt. In einem Workspace lässt sich unter Voice > Destinations auch ein tägliches Limit für jedes Zielland festlegen. Ein Anruf muss innerhalb beider Limits liegen. Die Höhe hängt von Ihrem Tarif ab.
• Die Kosten werden beim Anruf angezeigt, sobald sie berechnet wurden, mit voller Genauigkeit und ohne Steuern.

Eine Übersicht der Gebühren über mehrere Anrufe hinweg finden Sie unter Nutzung, Ausgaben und Rechnungen. Der CSV-Export unter Legs enthält die Dauer und die abrechenbare Zeit, aber keine Kostenspalte.

Nächste Schritte