Migration von Telserv zu Bird

Diese Anleitung richtet sich an Integrationen, die die Telserv-Partner-API (V1 oder V2) aufrufen, um Nummern zu kaufen, weiterzuleiten und freizugeben, und die jetzt zur Bird API wechseln.

Die Bird API bedient jedes Bird-Produkt, daher folgen ihre Nummern- und Voice-Operationen den eigenen Konventionen von Bird statt denen von Telserv. Die meisten Funktionen, die Ihre Integration nutzt, haben einen Bird-Aufruf. Endpunkte, Payloads, Identifier und Authentifizierung unterscheiden sich, planen Sie also ein Neuschreiben der Integration. Wo Bird eine Aufgabe anders erledigt, zeigt diese Anleitung wie.

Diese Anleitung wird laufend erweitert. Sie deckt ab, was Bird heute kann, und wächst mit der Migration. Falls eine Telserv-Operation, die Sie nutzen, hier nicht aufgeführt ist, muss sie erst bewertet und umgesetzt werden, bevor sie ergänzt werden kann; fragen Sie Ihren Migrationskontakt danach.

Bevor Sie beginnen

• Eine Bird-Organisation mit abgeschlossener Identitätsverifizierung, die für den ersten Nummernkauf erforderlich ist.
• Ein API-Schlüssel mit den Scopes, die die Rezepte verwenden: numbers auf Schreibebene für Nummern und Bestellungen, compliance auf Schreibebene für die eigenständigen Operationen zur Eigentumsdokumentation und voice_management auf Schreibebene für SIP-Trunks, Voice-Nummern und verifizierte Nummern. Der Testanruf benötigt außerdem voice:write, und das Lesen von Call Legs erfordert voice:read.
• Wallet-Guthaben. Bestellungen werden aus dem Wallet bezahlt. Wenn eine Bestellung abgelehnt wird erläutert die 402- und 412-Ablehnungen.

Die Nummern, die Ihre Integration in Telserv verwaltet, müssen nicht erneut gekauft werden. Sobald Ihre Nummern in Ihren Bird-Workspace verschoben wurden, erscheinen sie in GET /v1/numbers. Ihr Migrationskontakt bestätigt, wann das geschieht. Um den nda_-Identifier einer verschobenen Nummer zu erhalten, suchen Sie sie mit GET /v1/numbers?number=<digits>, geben Sie die Ziffern mit Ländervorwahl an und speichern Sie die id als NUMBER_ID.

Die Beispiele lesen Ihren Schlüssel aus BIRD_API_KEY und seinen regionalen Host aus BIRD_API_URL: https://eu1.platform.bird.com für einen bk_eu1_-Schlüssel oder https://us1.platform.bird.com für einen bk_us1_-Schlüssel. Die übrigen Variablen wie TRUNK_ID und NUMBER_ID enthalten einen Identifier aus einer früheren Antwort; jeder Schritt benennt den, den er setzt.

Was sich am Vertrag ändert

Die Bird API lehnt einen nicht erkannten Query-Parameter mit 422 und E01029 ab. Entfernen Sie Telserv-spezifische Filter wie city aus Ihren Anfragen, anstatt sie weiterzugeben.

Zwei Identifier für eine Nummer

Eine sprachfähige Nummer, die Ihrem Workspace zugewiesen ist, hat zwei Datensätze mit jeweils eigenem Identifier:

• Die Zuweisung, zurückgegeben von GET /v1/numbers. Ihr id beginnt bei einer dedizierten Nummer mit nda_ und bei einer geteilten mit nal_, und die number_id einer Bestellung ist der nda_-Identifier der gekauften Nummer. Verwenden Sie sie, um die Nummer zu lesen, zu benennen und zu referenzieren und um eine dedizierte Nummer freizugeben.
• Der Voice-Datensatz, vnu_, zurückgegeben von GET /v1/voice/numbers. Verwenden Sie ihn, um zu lesen und zu ändern, wohin die eingehenden Anrufe der Nummer geleitet werden. Eine Nummer ohne Sprachfähigkeit, z. B. eine reine SMS-Nummer, hat keinen Voice-Datensatz.

Die Voice-Operationen lehnen einen nda_- oder nal_-Identifier mit 422 ab. Um den Voice-Datensatz einer Nummer zu finden, listen Sie Voice-Nummern mit search auf, gesetzt auf die Ziffern der Nummer, und nehmen Sie den Eintrag, dessen provider.number_id der id der Zuweisung entspricht. Eine Nummer zu Ihrem SIP-Trunk routen zeigt die Anfrage, und Ihre Telefonnummern verwalten behandelt die Suche.

Telservs GET /numbers/{dnisId} wird in Bird zu zwei Leseoperationen: die Zuweisung für Status und Eigentumsdokumentation und der Voice-Datensatz für die Route.

Telserv-Operationen auf Bird abbilden

Jede Tabelle listet eine Aufgabe, den Telserv-Aufruf, der sie ausführte, und den Bird-Aufruf, der sie jetzt ausführt. Die Anmerkungen unter jeder Tabelle beschreiben, was sich in der Anfrage oder Antwort ändert.

Einkauf

• Suche. country_code ist erforderlich, eine Suche deckt also ein Land ab. prefix nimmt die nationalen Ziffern nach der Landesvorwahl entgegen: Telserv prefix=3170 wird zu country_code=NL&prefix=70. Grenzen Sie nach Vorwahl mit prefix anstelle von city ein sowie nach number_type und capabilities anstelle von productId.
• Unterlagen in Suchergebnissen. Jedes Ergebnis enthält ownership_registration_required anstelle des excludeNumbersRequireVerification-Filters. Ein Wert true bedeutet, dass die Nummer ab dem Kauf abgerechnet wird, aber keine SMS sendet und keine ein- oder ausgehenden Sprachanrufe überträgt, bis ihre Unterlagen genehmigt sind.
• Eine Nummer prüfen. Sie wird über ihre E.164-Nummer adressiert.
• Preise. Telserv gab pricing.staticPricing bei den detaillierten Abfragen einer Nummer und eines Produkts zurück. In Bird enthält jedes Suchergebnis den Preis für Ihre Organisation in pricing: setup_price anstelle von nrc und recurring_price pro recurring_period anstelle von mrc, mit intervals_per_charge für die Anzahl der Perioden, die eine Gebühr abdeckt. Eine Nummer mit Ihrer Referenz suchen und kaufen beschreibt die Preisfelder.
• Kaufen. Senden Sie number und eine optionale reference. Die Bestellung wird aus Ihrem Wallet bezahlt. Die meisten Bestellungen antworten mit 201; eine Bestellung, die auf einen Carrier wartet, antwortet mit 202, und Sie fragen den Status ab.
• Sichern. Die Bestellung der Nummer sichert sie. Prüfen Sie einen Kandidaten zuerst und bestellen Sie ihn dann.

Nummern

• Auflisten. Die Liste enthält die Ihnen aktuell zugewiesenen Nummern. Eine freigegebene Nummer, die Sie in Bird bestellt haben, bleibt über ihre Bestellung in GET /v1/numbers/orders sichtbar. Ihre Nummern abgleichen ordnet die Filter zu.
• Lesen. Status, Eigentumsdokumentation und Preis stehen auf der Zuweisung, die Route auf dem Voice-Datensatz. Das pricing-Objekt der Zuweisung mit recurring_price pro recurring_period und intervals_per_charge ersetzt pricing.staticPricing.mrc, und die Liste enthält es ebenfalls, wo Telservs GET /numbers das nicht tat.
• Ändern. name und reference stehen auf der Zuweisung, die Route auf dem Voice-Datensatz. Legen Sie einen erzwungenen Codec und eine Obergrenze für gleichzeitige Anrufe auf Ihrem SIP-Equipment fest. destinationDistributionType wird zu Gateway priority auf dem SIP-Trunk: FailOver gibt jedem Gateway einen anderen priority, und RoundRobin gibt ihnen denselben.
• Freigeben. DELETE behält die Nummer bis zum Ende des bereits bezahlten Zeitraums und gibt sie dann frei. POST …/release gibt sie sofort frei. Keiner der beiden Aufrufe akzeptiert ein Datum. Eine Nummer freigeben zeigt beide Anfragen.

Ziele und Profile

• SIP-Equipment. Ein Gateway gehört zum Trunk und bedient jede darauf geroutete Nummer. Nummern, die unterschiedliche Ziellisten brauchen, brauchen daher unterschiedliche Trunks. sortOrder wird zu priority. Klingelzeit und Zeitfenster legen Sie auf Ihrem SIP-Equipment fest.
• Weiterleitung. Setzen Sie forward_to und forward_as. forward_to muss eine Ihrer verifizierten Nummern sein; eine nicht verifizierte Nummer antwortet mit 412 und E21053. forward_as bestimmt, welche Nummer der weitergeleitete Anruf als Anrufer anzeigt. Eine Nummer hat jeweils nur eine Route. Um von SIP-Equipment auf eine Telefonnummer zurückzufallen, leiten Sie den Anruf von Ihrem SIP-Equipment weiter.
• Anrufe nicht mehr annehmen. Die Nummer lehnt Anrufe ab, bis Sie sie erneut routen. Um einen festen Standard anstelle eines Standardprofils beizubehalten, routen Sie die Nummer zu einem Trunk, der Ihre Standard-Gateways enthält.
• Profile. distributionType wird zu priority: FailOver gibt jedem Gateway eine andere priority, und RoundRobin gibt ihnen dieselbe. Die Verteilung wird pro Trunk festgelegt, daher benötigen Nummern mit unterschiedlicher Verteilung unterschiedliche Trunks. Der Platzhalter {dnis} wird zu {number} in destination_format, und ein prefixCLIP wird zum Text vor {number} in origination_format.
• Profil anwenden. Ein Trunk wird über seinen spt_-Identifier adressiert, während Telserv ein Profil über seinen Namen adressierte.

Dokumente und Endnutzerdaten

• Anforderungen. Telservs Bedingungskatalog deckte alle Produkte auf einmal ab; Bird liest jeweils ein Formular. Fragen Sie die Anforderungen einer Nummer mit subject_kind=number ab, mit ihrem nda_-Identifier als subject_id und ihrem country_code, oder lesen Sie ein Formular vor dem Kauf, indem Sie program auf den Nummerntyp setzen und kein subject_id angeben. Jeder Eintrag in fields ersetzt eine Telserv-Bedingung oder ein Endnutzer-Label: Unter seinem key geben Sie Ihre Antwort, und data_type document kennzeichnet einen Eintrag, der eine Datei erwartet.
• Dokumente. Laden Sie die Datei als multipart/form-data hoch statt als Base64-fileContent; Jedes Dokument hochladen listet die akzeptierten Dateien auf. Wenn Sie dieselbe Datei zweimal hochladen, erhalten Sie denselben Anhang. Ein Upload allein reicht nichts ein: Das erledigt die Einreichung, die seine attachment_id angibt.
• Endnutzerdaten und Dokumente zusammen. Telserv nahm jedes Dokument in einem eigenen Aufruf entgegen und die Endnutzerdaten als Label-Liste in einem weiteren. Bird nimmt alle Antworten, Textangaben und Dokumente, in einer Einreichung entgegen, und es gibt keine Entwürfe: Die Anfrage reicht die Antworten zur Prüfung ein. Verfolgen Sie danach ownership.next. Das Feld nennt eine Nachlieferung für Korrekturen und eine neue Einreichung nur dann, wenn eine nötig ist (Alle Antworten einreichen).
• Ersetzungen. Senden Sie nur die Antworten, die Sie ersetzen; die übrigen behalten ihren Prüfstand. Telserv nahm eine neue Datei für eine Bedingung an, solange die Verifizierung der Nummer ausstand, und die Datei setzte die Prüfung dieser Bedingung zurück. Bird ersetzt eine Antwort, die abgelehnt, abgelaufen oder noch nicht geliefert ist. Eine Antwort, die noch geprüft wird oder bereits akzeptiert ist, lehnt es ab, außer eine als editable_for_verifier_repair markierte Antwort, während eine von uns angeforderte Korrektur offen ist (Abgelehnte Antwort korrigieren).
• Fortschritt. ownership.status und ownership.next zeigen den Stand der Nummer. Jede Antwort hat ihren eigenen state, und eine abgelehnte enthält den reason der prüfenden Person. Bird sendet jedes Ergebnis außerdem per E-Mail an die Inhaber Ihrer Organisation und an die Person, die die Einreichung zuletzt eingereicht oder korrigiert hat. ownership ist in der Regel null, wenn die Nummer keine Unterlagen benötigt.

Eigentumsunterlagen einreichen zeigt die Anfragen, und Eigentumsunterlagen einer Nummer einreichen beschreibt den gesamten Ablauf, einschließlich der Einreichung über das Dashboard und mit der Bestellung.

Produkte und Stammdaten

Jedes Suchergebnis beschreibt sein Produkt mit number_type, capabilities und ownership_registration_required und enthält den Preis für Ihre Organisation anstelle des pricing.staticPricing des Produkts (nrc und mrc). Die Standardpreise von Bird finden Sie auf der Seite Telefonnummern-Preise. Telservs minutenbasierter sessionPricing hat bei diesen Abfragen kein Gegenstück; Sprachtarife finden Sie auf der Seite Sprach-Preise.

Telserv-Nummerntypen werden wie folgt auf number_type von Bird abgebildet:

Was anders funktioniert

Diese Telserv-Aufgaben funktionieren in Bird anders. Planen Sie dafür, bevor Sie eine Integration umstellen, die auf eine davon angewiesen ist.

• Unterlagen. Reichen Sie die Dokumente und Endnutzerdaten einer Nummer in einer einzigen Übermittlung ohne Entwürfe ein, und korrigieren Sie abgelehnte Antworten per Nachreichung.
• Reservierungen. Bestellen Sie die Nummer, sobald Sie sich entschieden haben; die Bestellung sichert sie.
• Anrufeinstellungen pro Nummer. Wenden Sie einen erzwungenen Codec, eine Obergrenze für gleichzeitige Anrufe, Klingelzeit und Zeitfenster auf Ihrem SIP-Equipment an.
• Ein Freigabedatum. Bird gibt eine Nummer am Ende des bezahlten Zeitraums oder sofort frei, nicht zu einem von Ihnen gewählten Datum. Behalten Sie die Kündigungsdaten, die Sie an Telserv gesendet haben, auf Ihrer Seite und handeln Sie bei jedem einzelnen, wenn es fällig wird.
• Wallet-Guthaben. Prüfen Sie das Guthaben und laden Sie es im Dashboard auf.

Eine Nummer mit Ihrer Referenz suchen und kaufen

Durchsuchen Sie ein Land. Kombinieren Sie number_type, capabilities und prefix, um die Ergebnisse einzugrenzen:

curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Jedes Ergebnis enthält ein pricing-Objekt mit dem Preis, den Ihre Organisation für die Nummer zahlt, netto ohne Steuern und in Ihrer Abrechnungswährung, mit allen mit Bird vereinbarten Preisen:

• setup_price wird einmalig bei der Bestellung der Nummer berechnet. Eine veröffentlichte Gebühr von null hat einen amount von "0". Das Feld selbst ist null, wenn keine Einrichtungsgebühr anfällt, und ebenso immer dann, wenn recurring_price den Wert null hat, weil diese Nummer nicht bestellt werden kann.
• recurring_price ist der Tarif pro recurring_period.
• intervals_per_charge gibt an, wie viele recurring_period eine Abrechnung umfasst. Die wiederkehrende Gebühr vor Steuern ergibt sich aus recurring_price multipliziert mit intervals_per_charge und wird abgebucht, wenn die Nummer Ihrem Workspace zugewiesen wird, sowie bei jeder Verlängerung; die Einrichtungsgebühr ist separat. Bei einer Bestellung, die auf einen Carrier wartet, erfolgt die Zuweisung, sobald die Bestellung abgeschlossen ist.

Die API-Referenz zeigt ein Beispielergebnis. Ein Ergebnis mit pricing.recurring_price: null nennt keinen wiederkehrenden Preis. Vertrieb kontaktieren, um vor der Bestellung einen Preis für dieses Land und diesen Nummerntyp zu erhalten.

Das Dashboard und API verwenden denselben Organisationspreis, einschließlich der Umrechnung in Ihre Abrechnungswährung. Ein Preisabruf sperrt kein Angebot: Tarif- oder Wechselkursänderungen vor einer späteren Belastung können deren Betrag ändern. Schlägt die Abfrage fehl, gibt die Suche 503 mit E14009 zurück. Versuchen Sie den Abruf mit exponentiellem Backoff erneut; ein Abfragefehler bedeutet nie, dass die Nummer nichts kostet.

Um einen Kandidaten und seinen Preis vor der Bestellung zu prüfen, lesen Sie ihn mit GET /v1/numbers/available/{number}. Ein 404 bedeutet, dass die Nummer nicht mehr zum Verkauf steht.

Bestellen Sie die Nummer mit der Referenz, die Sie in Telserv verwendet haben, und wählen Sie einen Idempotenzschlüssel, den Sie für jeden erneuten Versuch dieses Kaufs aufbewahren:

curl --request POST "$BIRD_API_URL/v1/numbers/orders" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-CUST-778812" \
  --data '{"number": "+31612345678", "reference": "CUST-778812"}'

Eine 201-Antwort enthält status: completed und eine number_id, den nda_-Bezeichner der Nummer. Speichern Sie ihn als NUMBER_ID. Eine 202-Antwort bedeutet, dass die Bestellung auf einen Carrier wartet: Fragen Sie die Bestellung ab, bis ihr status den Wert completed oder failed hat. Eine bereits berechnete Einrichtungsgebühr wird nicht erstattet, wenn die Bestellung anschließend fehlschlägt. Die Referenz wird auf der Nummer gesetzt, wenn die Bestellung abgeschlossen ist. Sie fasst bis zu 100 Zeichen und muss nicht eindeutig sein.

Wenn Sie eine Bestellung für eine Nummer, die Ihrem Workspace bereits zugewiesen ist, erneut versuchen, erhalten Sie die bestehende Bestellung zurück. Ein erneuter Versuch wird also nicht doppelt berechnet. Nummer kaufen und freigeben erläutert die Ablehnungen.

Um eine Referenz später zu setzen oder zu ändern, senden Sie reference (und optional name) an PATCH /v1/numbers/{number_id}. Senden Sie null, um ein Feld zu leeren.

Prüfen, ob eine Nummer Anrufe übertragen kann

Eine Nummer, deren status den Wert pending_ownership_registration hat, ist zugewiesen und wird abgerechnet, sendet aber keine SMS und lehnt ein- und ausgehende Sprachanrufe ab, bis ihre Eigentumsunterlagen genehmigt sind. Bevor Sie eine Nummer routen oder einen Testanruf an sie tätigen, lesen Sie sie mit GET /v1/numbers/{number_id} und prüfen Sie, ob status den Wert active hat. Falls der Status ausstehend ist, reichen Sie die Eigentumsunterlagen ein. Der Status einer zugewiesenen Nummer erläutert jeden Wert.

Die folgenden Beispiele verwenden eine niederländische Mobilfunknummer. Prüfen Sie den status Ihrer eigenen Nummer auf dieselbe Weise, unabhängig vom Land.

Eigentumsunterlagen einreichen

Telserv nahm die Unterlagen einer Nummer mit einem POST /numbers/{dnisId}/documents pro Dokument und einem POST /numbers/{dnisId}/enduserdata für alle Labels entgegen. Bird nimmt beides in einer einzigen Übermittlung entgegen, nachdem Sie die Dokumente hochgeladen haben.

1. Lesen Sie die country_code der Nummer und speichern Sie sie als COUNTRY_CODE. Der Befehl extrahiert sie mit jq; lesen Sie sie manuell ab, wenn Sie jq nicht verwenden:

   Codebeispiel

   COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

2. Lesen Sie, was das Land der Nummer verlangt. Jeder Eintrag in fields enthält den key, unter dem Sie antworten, einen data_type und required, das angibt, ob Sie ihn beantworten müssen. Speichern Sie die in der Antwort genannte program als PROGRAM:

   Codebeispiel

   curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
     --header "Authorization: Bearer $BIRD_API_KEY"

   Ein 422 mit E19001 bedeutet, dass es für dieses Land kein Eigentumsformular gibt.

3. Laden Sie jedes Dokument, das ein document-Feld verlangt, als Datei statt als Base64-fileContent hoch. Speichern Sie die id aus der Antwort, den tca_-Identifier des Anhangs, als ATTACHMENT_ID:

   Codebeispiel

   curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --form "file=@registration-certificate.pdf"

4. Übermitteln Sie alle Antworten auf einmal: einen Eintrag für jedes Feld, dessen required den Wert true hat, und für jedes optionale Feld, für das Sie eine echte Antwort haben, mit den Endnutzerdaten als value und jedem Dokument als attachment_id. Lassen Sie ein optionales Feld weg, statt einen Wert dafür zu erfinden. Das Beispiel zeigt zwei Antworten; ergänzen Sie die übrigen Pflichtantworten, bevor Sie es senden. Diese Anfrage reicht die Antworten zur Prüfung ein. Speichern Sie die id aus der Antwort, den csb_-Identifier der Übermittlung, als SUBMISSION_ID:

   Codebeispiel

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-CUST-778812" \
     --data '{"subject_kind": "number", "subject_id": "'"$NUMBER_ID"'", "program": "'"$PROGRAM"'", "country_code": "'"$COUNTRY_CODE"'", "answers": [{"key": "business_registration_number", "value": "90012768"}, {"key": "business_registration_certificate", "attachment_id": "'"$ATTACHMENT_ID"'"}]}'

   Eine 201-Antwort gibt die Übermittlung zurück. Ein 422 reicht nichts ein: Korrigieren Sie den Body und senden Sie ihn mit einem neuen Idempotenzschlüssel, da der alte Schlüssel die Ablehnung erneut liefert. Alle Antworten übermitteln erläutert jede Ablehnung.

5. Wenn ein Prüfer eine Antwort ablehnt, ersetzen Sie nur diese Antwort, wie unter Abgelehnte Antwort korrigieren beschrieben:

   Codebeispiel

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-fix-1-CUST-778812" \
     --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

Um die Unterlagen gleich beim Kauf einzureichen, senden Sie dasselbe answers im compliance-Block von POST /v1/numbers/orders. Diese Bestellung verwendet den bestehenden numbers-Scope auf Schreibebene, auch wenn sie Unterlagen enthält.

Verfolgen Sie die Prüfung über ownership.status auf GET /v1/numbers/{number_id}. Die Angaben sind eine rechtsverbindliche Erklärung im Namen Ihres Unternehmens. Reichen Sie daher nur Angaben ein, die eine dafür verantwortliche Person bestätigt hat. Eigentumsunterlagen einer Nummer einreichen beschreibt jede Anfrage, die Prüfung und das Einreichen mit der Bestellung.

Eine Nummer zu Ihrem SIP-Trunk routen

Eine neue Nummer hat keine eigene Route und folgt daher der Standardroute Ihres Workspace. Diese Standardroute ist anfangs reject, doch in einem Workspace, der bereits eine festgelegt hat, beantwortet die neue Nummer Anrufe nach dieser Route, sobald sie zugewiesen ist. Um ihre Anrufe an Ihr Equipment zu liefern, erstellen Sie einen SIP-Trunk mit aktiviertem Inbound-Calling, fügen Sie ein Gateway hinzu und verweisen Sie die Nummer auf den Trunk. SIP-Trunks beschreibt, wie Sie Ihr Equipment mit dem Trunk verbinden.

1. Erstellen Sie den Trunk mit aktiviertem Inbound-Calling. Speichern Sie den id aus der Antwort, den spt_-Identifier des Trunks, als TRUNK_ID:

   Codebeispiel

   curl --request POST "$BIRD_API_URL/v1/voice/trunks" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: trunk-production-pbx" \
     --data '{"name": "Production PBX", "inbound_enabled": true}'

2. Fügen Sie ein Gateway hinzu. Standardmäßig empfängt das Gateway die gewählte und die anrufende Nummer im E.164-Format mit ihrem +. Wenn Ihre Anlage Nummern ohne + erwartet, wie es Telservs {dnis}-Platzhalter tat, setzen Sie destination_format für die gewählte Nummer und origination_format für die anrufende Nummer auf {number}:

   Codebeispiel

   curl --request POST "$BIRD_API_URL/v1/voice/trunks/$TRUNK_ID/gateways" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: gateway-pbx-primary" \
     --data '{"sip_uri": "sip:pbx.example.com:5060", "priority": 0, "destination_format": "{number}", "origination_format": "{number}"}'

   Für Failover fügen Sie ein zweites Gateway hinzu; Was ein Gateway benötigt erklärt priority und die Nummernformate. Wenn Sie dasselbe Gateway ohne Idempotenzschlüssel erneut erstellen, lautet die Antwort 409 mit E21047.

3. Finden Sie den Voice-Datensatz der Nummer. Suchen Sie mit den Ziffern der Nummer und nehmen Sie den id des Eintrags, dessen provider.number_id die id der Zuweisung ist. Speichern Sie ihn als VOICE_NUMBER_ID:

   Codebeispiel

   curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \
     --header "Authorization: Bearer $BIRD_API_KEY"

4. Verweisen Sie die Nummer auf den Trunk:

   Codebeispiel

   curl --request PATCH "$BIRD_API_URL/v1/voice/numbers/$VOICE_NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"inbound_configuration": {"route": {"type": "trunk", "trunk_id": "'"$TRUNK_ID"'"}}}'

   Eine 200-Antwort zeigt die neue Route. Ein Trunk mit deaktiviertem Inbound-Calling antwortet mit 412 und E21052.

Wenn Sie Inbound-Calling auf einem Trunk deaktivieren oder den Trunk löschen, kehrt jede dorthin geroutete Nummer zur Standardroute Ihres Workspace zurück, und erneutes Aktivieren stellt diese Routen nicht wieder her. Anrufe an einen SIP-Trunk zustellen erklärt dies sowie die Routen trunk, forward und reject.

Ihre Nummern abgleichen

Durchlaufen Sie die Liste mit der größten Seitengröße. Übergeben Sie den next_cursor jeder Seite als NEXT_CURSOR, um die nächste Seite zu lesen, bis next_cursor den Wert null hat. Die Liste gibt keine Gesamtanzahl zurück.

curl "$BIRD_API_URL/v1/numbers?limit=100" \
  --header "Authorization: Bearer $BIRD_API_KEY"

curl "$BIRD_API_URL/v1/numbers?limit=100&starting_after=$NEXT_CURSOR" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Telservs Listenfilter werden wie folgt auf die von Bird abgebildet:

Eine Nummer in Ihrer Liste finden beschreibt jeden Filter im Detail.

Jeder Eintrag enthält pricing mit recurring_price pro recurring_period und intervals_per_charge. Sofern der Preis nicht für die Nummer festgelegt ist, ist recurring_price der aktuelle Tarif Ihrer Organisation, und jede Verlängerung berechnet den zum Zeitpunkt der Verlängerung geltenden Tarif, sodass ein bereits abgerechneter Betrag davon abweichen kann. Alle Ihre Nummern auflisten erklärt, in welcher Währung jede Nummer abgerechnet wird, wann pricing oder seine Preise null sind und was zu tun ist, wenn pricing.error gesetzt ist.

Eine freigegebene Nummer verschwindet aus dieser Liste, und ein Lesen über number_id antwortet mit 404. Wenn Sie sie in Bird bestellt haben, bleibt ihre abgeschlossene Bestellung in GET /v1/numbers/orders sichtbar.

Eine Nummer freigeben

Beide Anfragen gelten für eine dedizierte Nummer, adressiert über ihren nda_-Bezeichner; eine geteilte Nummer wird mit E14002 abgelehnt. Um die Nummer bis zum Ende des bereits bezahlten Zeitraums zu behalten, kündigen Sie sie:

curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: cancel-CUST-778812"

Eine 202-Antwort gibt die Nummer mit releases_at zurück, dem Ende ihres bezahlten Zeitraums. Die Nummer behält bis dahin ihren aktuellen Status, ihr Abonnement verlängert sich nicht, und sie wird zu diesem Zeitpunkt freigegeben. Eine erneute Anfrage gibt dasselbe releases_at zurück, und eine Kündigung kann nicht rückgängig gemacht werden. Eine Nummer ohne zugrunde liegendes Abonnement wird sofort freigegeben, und die Antwort ist 200 mit status der Nummer auf released gesetzt.

Um die Nummer jetzt freizugeben, auch wenn bereits eine Kündigung geplant ist:

curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: release-CUST-778812"

Eine 204-Antwort bedeutet, dass die Nummer sofort freigegeben ist. Der Rest des laufenden Zeitraums wird nicht erstattet.

Solange eine Verlängerungszahlung für die Nummer überfällig ist, antworten beide Anfragen mit 409 und E03015, bis sie bezahlt ist.

Keine der beiden Anfragen nimmt ein Datum entgegen. Behalten Sie daher den Zeitplan, den Sie an Telserv gesendet haben, als requestedCancelDate auf Ihrer Seite. Um eine Nummer bis zu ihrem Datum zu behalten, kündigen Sie sie, sobald das Datum in ihren aktuellen Abrechnungszeitraum fällt: Sie wird freigegeben, wenn dieser Zeitraum endet, also am oder nach dem Datum. Um sie genau am Datum aufzugeben, geben Sie sie an diesem Tag frei. Eine Nummer freigeben beschreibt, was jede Anfrage mit der Nummer und ihren Gebühren macht und wie ein erneuter Versuch wirkt.

Einen Testanruf an Ihre Nummer tätigen

Um eine Route durchgängig zu prüfen, rufen Sie die Nummer von einer anderen Nummer an, die Ihr Workspace als Anrufer-ID präsentieren darf. Das Land der Nummer muss in Ihren Voice-Zielen aktiviert sein, sonst kommt der Anruf nicht durch. Die folgende Anfrage führt eine Inline-Sequenz aus, die auflegt, sobald der Anruf angenommen wird. Eine gespeicherte Sequenz ist daher nicht nötig. Es handelt sich um einen echten Anruf, und die normalen Gesprächsgebühren fallen an.

Speichern Sie die Anfrage als test-call.json. Tragen Sie in from die Anrufer-ID ein, die Sie präsentieren, also eine eigene oder verifizierte Nummer Ihres Workspace, und in to die zu testende Nummer:

{
  "from": "+31612345679",
  "to": "+31612345678",
  "sequence": {
    "definition": {
      "schema_version": 1,
      "expression_environment": "bird.cel.v1",
      "nodes": [
        {
          "id": "entry",
          "type": "trigger.start_call",
          "type_version": 1,
          "config": {},
          "input": {},
          "connections": { "event": { "node_id": "end", "port": "input" } }
        },
        { "id": "end", "type": "voice.hangup", "type_version": 1, "config": {}, "input": {} }
      ]
    },
    "entry_node_id": "entry",
    "trigger_data": {}
  }
}

Senden Sie sie ab:

curl --request POST "$BIRD_API_URL/v1/voice/calls" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${TEST_CALL_KEY:?Set TEST_CALL_KEY once for this test call}" \
  --data-binary @test-call.json

Setzen Sie TEST_CALL_KEY für jeden Test auf einen neuen Wert und verwenden Sie ihn wieder, wenn Sie denselben Test nach einem Timeout oder einem unklaren Ergebnis erneut versuchen: Derselbe Schlüssel und dieselbe Anfrage innerhalb von drei Stunden wiederholen die erste Annahme, statt einen zweiten Anruf zu tätigen. Eine 202-Antwort nimmt den Anruf an und gibt seine initial_leg_id zurück. Die Annahme beweist nicht, dass der Anruf verbunden wurde: Lesen Sie den Leg mit GET /v1/voice/legs/{leg_id} aus, oder listen Sie die an die Nummer getätigten Legs mit GET /v1/voice/legs und seinem to-Filter auf, und prüfen Sie, ob Ihre Anlage den Anruf empfangen hat. Sprachanruf erstellen behandelt die Anforderungen an Anrufer-ID und Ziel sowie die Regeln für erneute Versuche.

Nächste Schritte

• Nummer kaufen und freigeben
• Ihre Telefonnummern verwalten
• Eigentumsunterlagen einer Nummer einreichen
• Anrufe empfangen
• SIP-Trunks
• Idempotenz