Ihre Telefonnummern verwalten

Sobald eine Nummer Ihrem Workspace zugewiesen ist, können Sie über die Numbers-API auflisten, was Sie halten, eine Nummer anhand beliebiger Kennungen finden, sie mit einem Namen und Ihrer eigenen Referenz versehen und sie kündigen oder freigeben, wenn Sie sie nicht mehr benötigen. Zum Lesen benötigen Sie einen API-Schlüssel mit dem Scope numbers auf Lesestufe; zum Ändern, Kündigen oder Freigeben einer Nummer ist Schreibstufe erforderlich.

Die Seite Numbers im Dashboard zeigt dieselben Nummern.

Alle Nummern auflisten, die Sie halten

GET /v1/numbers gibt die Nummern zurück, die Ihrem Workspace aktuell zugewiesen sind, neueste zuerst, dedizierte und geteilte gleichermaßen. Jede Seite enthält 25 Nummern, sofern Sie nicht mit limit bis zu 100 anfordern.

Die Liste ist per Cursor paginiert. Übergeben Sie den next_cursor einer Seite als starting_after, um die nächste Seite zu lesen, und stoppen Sie, wenn next_cursor den Wert null hat. Die SDKs folgen dem Cursor automatisch. Die folgenden Beispiele schränken die Liste auf country_code: "GB" ein; lassen Sie den Filter weg, um alle Nummern durchzugehen, die Sie halten:

for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  console.log(allocated.number, allocated.kind, allocated.status);
}

for allocated in client.numbers.list(country_code="GB"):
    print(allocated.number, allocated.kind, allocated.status)

for allocated, err := range client.Numbers.List(context.Background(), bird.NumbersListParams{
	CountryCode: "GB",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(allocated.Number, allocated.Kind, allocated.Status)
}

$page = $bird->numbers->list(['country_code' => 'GB']);
foreach ($page as $allocated) {
    echo $allocated->getNumber(), ' ', $allocated->getKind(), ' ', $allocated->getStatus(), "\n";
}

curl "https://us1.platform.bird.com/v1/numbers?country_code=GB" \
  -H "Authorization: Bearer bk_us1_..."

Verwenden Sie den regionalen Host, der zum bk_{region}_-Präfix Ihres Schlüssels passt: https://us1.platform.bird.com oder https://eu1.platform.bird.com.

Die Liste enthält keine Gesamtzahl. Um Ihre Nummern zu zählen, durchlaufen Sie alle Seiten bis zum Ende und zählen die Einträge. Die Übergabe von include_total wird mit 422 und E01029 abgelehnt.

Jeder Eintrag enthält seinen status und ownership. Wenn ein Land keine Eigentumsnachweise verlangt, ist ownership gleich null. Die Numbers-Übersicht erklärt, was jeder Status bedeutet. Wie Sie die Eigentumsnachweise einreichen, auf die eine Nummer wartet, erfahren Sie unter Eigentumsnachweise für eine Nummer einreichen.

Jeder Eintrag enthält außerdem pricing, also den Betrag, den Ihre Organisation für die Nummer zahlt, netto ohne Steuern:

recurring_price ist Ihr Tarif pro recurring_period, in der Währung, in der die Nummer abgerechnet wird. Das ist Ihre Abrechnungswährung, es sei denn, das Abonnement der Nummer begann, bevor sich Ihre Abrechnungswährung geändert hat; eine solche Nummer behält die Währung ihres Abonnements, die currency_code angibt.
intervals_per_charge gibt an, wie viele recurring_periods eine Verlängerung abrechnet. Die wiederkehrende Gebühr vor Steuern ist recurring_price multipliziert mit intervals_per_charge. Ein für die Nummer festgelegter Preis deckt den gesamten Zeitraum ab, daher ist sein intervals_per_charge gleich 1.

pricing ist null bei einer shared-Nummer und bei einer Nummer ohne aktives Abonnement. Wenn für das Abonnement einer Nummer kein Preis gilt, sind ihre Preise null mit pricing.error: null; kontaktieren Sie den Vertrieb, um einen Preis dafür zu erhalten. Wenn der Preis nicht gelesen werden konnte, enthält pricing.error den Wert E14009 und die Preise sind null. Versuchen Sie GET /v1/numbers/{number_id} mit exponentiellem Backoff erneut. Die Nummer bleibt verwaltbar; wiederholen Sie ein bereits abgeschlossenes Update oder eine abgeschlossene Kündigung nicht, um ihren Preis zu aktualisieren.

Dashboard und API verwenden dieselbe Preisermittlung. Ein fester Preis behält seine bestehenden Bedingungen; andernfalls ist dies der aktuelle Tarif, der sich vor der Verlängerung ändern kann. Er gibt nicht an, was eine frühere Bestellung berechnet hat. Eine Nummer mit gesetztem releases_at behält ihr pricing bis zur Freigabe, und es folgt keine Verlängerung.

Eine Nummer in Ihrer Liste finden

Die Listenfilter werden kombiniert, sodass ein Länder- oder Fähigkeitsfilter weiterhin zusammen mit den anderen gilt.

number sucht eine einzelne Nummer, egal wie Ihre Einträge sie schreiben. +31612345678 und 0031612345678 werden zur selben Nummer aufgelöst. Eine nationale Schreibweise wie 0612345678 wird nur aufgelöst, wenn country_code das Land angibt:

Codebeispiel

curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."

Wenn Sie eine vollständige Nummer oder eine nationale Schreibweise mit ihrem country_code ohne weiteren Filter übergeben, bedeutet ein leeres data-Array, dass die Nummer nicht Ihrem Workspace zugewiesen ist. Das schließt eine von Ihnen freigegebene Nummer ein. Eine nationale Schreibweise ohne country_code, etwa 0612345678 allein, gibt ebenfalls eine leere Liste zurück und beweist daher nicht, dass die Nummer nicht Ihnen gehört.

search gleicht einen Teil der Nummer, ihres Namens oder ihrer Referenz ab, ohne Berücksichtigung der Groß-/Kleinschreibung. reference gibt die Nummern mit exakt dieser Referenz zurück, unter Berücksichtigung der Groß-/Kleinschreibung:

Codebeispiel

curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."

prefix gibt Nummern zurück, die mit den angegebenen Ziffern beginnen, und die Bedeutung dieser Ziffern hängt von country_code ab:

Mit country_code sind die Ziffern nationale Ziffern, die direkt nach der Landesvorwahl abgeglichen werden. prefix=6&country_code=NL gibt niederländische Nummern zurück, die mit +31 6 beginnen.
Ohne country_code werden die Ziffern ab dem Anfang der vollständigen Nummer abgeglichen. prefix=6 allein gibt Nummern zurück, deren Landesvorwahl mit 6 beginnt, etwa australische +61-Nummern, und findet daher keine Ihrer niederländischen Mobilnummern. Es werden auch Kurzcodes gefunden, die mit diesen Ziffern beginnen.

Einer Nummer einen Namen geben und Ihre Referenz setzen

Eine Nummer trägt zwei eigene Labels. name unterscheidet Ihre Nummern voneinander, zum Beispiel Support line. reference enthält einen Bezeichner aus Ihren eigenen Einträgen, etwa eine Kunden- oder Filial-ID, und muss nicht eindeutig sein. Beide gelten für dedizierte und geteilte Nummern und sind bis zu 100 Zeichen lang.

Setzen Sie sie mit PATCH /v1/numbers/{number_id}. Ein Feld, das Sie weglassen, behält seinen aktuellen Wert, und ein Feld, das Sie als null senden, wird gelöscht. Führende und abschließende Leerzeichen werden entfernt.

const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);

allocated = client.numbers.update(
    "nda_01krdgeqcxet5s7t44vh8rt9mg", name="Support line", reference="STORE-042"
)
print(allocated.name, allocated.reference)

allocated, err := client.Numbers.Update(ctx, "nda_01krdgeqcxet5s7t44vh8rt9mg", bird.NumbersUpdateParams{
	Name:      bird.Value("Support line"),
	Reference: bird.Value("STORE-042"),
})
if err != nil {
	log.Fatal(err)
}
if allocated.Name != nil {
	fmt.Println(*allocated.Name)
}
if allocated.Reference != nil {
	fmt.Println(*allocated.Reference)
}

$allocated = $bird->numbers->update(
    'nda_01krdgeqcxet5s7t44vh8rt9mg',
    (new \MessageBird\Wire\Model\NumberUpdate())->setName('Support line')->setReference('STORE-042'),
);
echo $allocated->getName(), ' ', $allocated->getReference(), "\n";

curl -X PATCH "https://{region}.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line",
    "reference": "STORE-042"
  }'

Die Antwort ist 200 mit der aktualisierten Nummer. Um die Referenz zu löschen und den Namen beizubehalten, senden Sie die Referenz als null und lassen Sie den Namen weg:

Codebeispiel

curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'

Um die Referenz beim Kauf der Nummer zu setzen, übergeben Sie reference bei POST /v1/numbers/orders. Eine Bestellung, die auf einen Carrier warten muss, behält die Referenz, bis die Nummer zugewiesen ist, und die Nummer trägt sie ab dann.

Den Voice-Eintrag finden, der eine Nummer routet

Eine Nummer mit Voice hat zwei Identifier. Die id auf GET /v1/numbers beginnt mit nda_ bei einer dedizierten Nummer und nal_ bei einer geteilten, und die Numbers-Operationen verwenden sie. Die Voice-Operationen, einschließlich derjenigen, die festlegt, wohin eingehende Anrufe gehen, verwenden den Voice-Eintrag der Nummer, dessen id mit vnu_ beginnt. Die Übergabe einer nda_- oder nal_-ID an eine Voice-Operation wird mit 422 abgelehnt.

Um von einem zum anderen zu gelangen, suchen Sie die Voice-Nummern anhand der Telefonnummer. Das erfordert den Scope voice_management auf Lesestufe:

Codebeispiel

curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."

Die id des Eintrags ist der vnu_-Identifier, und seine provider.number_id ist der nda_- oder nal_-Identifier derselben Nummer. Anrufe empfangen zeigt, wie Sie die Nummer von dort aus routen.

Der Voice-Eintrag hat eine eigene name. Eine Nummer mit PATCH /v1/numbers/{number_id} zu benennen, lässt den Namen des Voice-Eintrags unverändert, und umgekehrt gilt dasselbe.

Eine Nummer freigeben

Sie können eine dedizierte Nummer auf zwei Wegen zurückgeben:

Am Ende des bezahlten Zeitraums. DELETE /v1/numbers/{number_id} stoppt die Verlängerung der Nummer. Sie funktioniert bis zum Ende des aktuellen Abrechnungszeitraums weiter und wird dann freigegeben. Die 202-Antwort gibt die Nummer mit releases_at auf diesen Zeitpunkt gesetzt zurück, und eine erneute Anfrage liefert dasselbe releases_at. Eine Kündigung kann nicht rückgängig gemacht werden. Eine Nummer ohne Abonnement, etwa eine ohne Gebühr zugewiesene, wird sofort freigegeben, und die Antwort ist 200 mit status der Nummer auf released gesetzt.
Sofort. POST /v1/numbers/{number_id}/release gibt die Nummer sofort frei, auch eine bereits zur Kündigung vorgemerkte. Der Rest des aktuellen Zeitraums wird nicht erstattet. Eine Nummer kaufen und freigeben zeigt den Aufruf in jedem SDK.

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

Unabhängig davon, welche Freigabeoption Sie wählen, senden Sie die Anfrage mit einem Idempotency-Key, damit ein erneuter Versuch sicher ist: Derselbe Schlüssel liefert die erste Antwort mit einem Idempotency-Replay: true-Header erneut, während eine neue Anfrage für eine bereits freigegebene Nummer mit 404 und E01008 antwortet. Idempotenz erklärt, wie lange ein Schlüssel aufbewahrt wird.

Bis eine geplante Kündigung wirksam wird, ist die Nummer wie gewohnt abrufbar und trägt releases_at. Nach der Freigabe:

Die Nummer funktioniert nicht mehr für Sie, und ihr Abonnement verlängert sich nicht.
GET /v1/numbers/{number_id} und der Voice-Eintrag der Nummer antworten mit 404, und die Nummer verschwindet aus GET /v1/numbers.
Die Bestellung der Nummer bleibt in GET /v1/numbers/orders erhalten, und ihr number_id antwortet jetzt mit 404.
Die Nummer geht in eine 30-tägige Sperrfrist, bevor sie wieder zum Verkauf stehen kann. Sie können dieselbe Nummer also nicht sofort erneut kaufen.

Nächste Schritte

Anrufe empfangen leitet eine Nummer an einen SIP-Trunk, eine Weiterleitung oder eine Sequenz weiter.
Eine Nummer kaufen und freigeben führt den Kauf über die API durch.
Numbers-API-Referenz dokumentiert jede Operation und jedes Feld.

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Implementierungs-Briefing erhalten

Ihre Telefonnummern verwalten

Alle Nummern auflisten, die Sie halten

Eine Nummer in Ihrer Liste finden

Einer Nummer einen Namen geben und Ihre Referenz setzen

Den Voice-Eintrag finden, der eine Nummer routet

Eine Nummer freigeben

Nächste Schritte

Verwandte Ressourcen