Zarządzanie numerami telefonów

Gdy numer zostanie przypisany do Twojego obszaru roboczego, API numerów pozwala wyświetlić posiadane numery, wyszukać jeden numer po dowolnym identyfikatorze, oznaczyć go nazwą i własnym identyfikatorem oraz anulować lub zwolnić go, gdy nie jest już potrzebny. Odczyt wymaga klucza API z uprawnieniem numbers na poziomie odczytu; zmiana, anulowanie lub zwolnienie numeru wymaga poziomu zapisu.

Strona Numbers w panelu wyświetla te same numery.

Wyświetl wszystkie posiadane numery

GET /v1/numbers zwraca numery aktualnie przypisane do Twojego obszaru roboczego, od najnowszych, dedykowane i współdzielone. Każda strona zawiera 25 numerów, chyba że zażądasz do 100 za pomocą limit.

Lista jest stronicowana kursorem. Przekaż next_cursor strony z powrotem jako starting_after, aby odczytać następną stronę, i zatrzymaj się, gdy next_cursor wynosi null. SDK podążają za kursorem automatycznie. Poniższe przykłady zawężają listę do country_code: "GB"; pomiń filtr, aby przejść przez wszystkie posiadane numery:

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_..."

Użyj hosta regionalnego pasującego do prefiksu bk_{region}_ Twojego klucza: https://us1.platform.bird.com lub https://eu1.platform.bird.com.

Lista nie zawiera sumy. Aby policzyć numery, przejdź strony do końca i zlicz wpisy. Przekazanie include_total jest odrzucane z 422 i E01029.

Każdy wpis zawiera status i ownership. Jeśli dany kraj nie wymaga dokumentów potwierdzających własność, ownership ma wartość null. Przegląd numerów wyjaśnia znaczenie każdego statusu. Aby złożyć dokumenty, na które czeka numer, zobacz Złóż dokumenty potwierdzające własność numeru.

Każdy wpis zawiera także pricing, czyli to, ile Twoja organizacja płaci za numer, netto:

recurring_price to Twoja stawka za recurring_period, w walucie, w której naliczana jest opłata za numer. Jest to Twoja waluta rozliczeniowa, chyba że subskrypcja numeru rozpoczęła się przed zmianą Twojej waluty rozliczeniowej; taki numer zachowuje walutę swojej subskrypcji, którą podaje currency_code.
intervals_per_charge określa, ile recurring_period nalicza jedno odnowienie. Opłata cykliczna przed opodatkowaniem to recurring_price pomnożona przez intervals_per_charge. Cena ustalona dla numeru obejmuje cały okres, więc intervals_per_charge wynosi 1.

pricing ma wartość null dla numeru shared oraz dla numeru bez aktywnej subskrypcji. Gdy dla subskrypcji numeru nie obowiązuje żadna cena, jego ceny mają wartość null z pricing.error: null; skontaktuj się z działem sprzedaży, aby ustalić cenę. Jeśli nie udało się odczytać ceny, pricing.error zawiera E14009, a ceny mają wartość null. Spróbuj ponownie GET /v1/numbers/{number_id} z wykładniczym wycofaniem. Numer pozostaje dostępny do zarządzania; nie powtarzaj zakończonej aktualizacji ani anulowania, aby odświeżyć jego cenę.

Panel i API korzystają z tego samego mechanizmu ustalania ceny. Cena stała zachowuje dotychczasowe warunki; w przeciwnym razie jest to bieżąca stawka, która może się zmienić przed odnowieniem. Nie pokazuje, ile zostało naliczone przy wcześniejszym zamówieniu. Numer z ustawionym releases_at zachowuje swoje pricing do momentu zwolnienia, a odnowienie już nie następuje.

Znajdź numer na swojej liście

Filtry listy łączą się, więc filtr kraju lub funkcji nadal działa obok pozostałych.

number wyszukuje jeden numer niezależnie od tego, jak jest zapisany w Twoich danych. +31612345678 i 0031612345678 prowadzą do tego samego numeru. Zapis krajowy, taki jak 0612345678, jest rozpoznawany tylko wtedy, gdy country_code wskazuje kraj:

Przykład kodu

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

Gdy przekazujesz pełny numer lub zapis krajowy z jego country_code i żaden inny filtr, pusta tablica data oznacza, że numer nie jest przypisany do Twojego obszaru roboczego, w tym numer, który zwolniłeś. Zapis krajowy bez country_code, na przykład samo 0612345678, również zwraca pustą listę, więc nie dowodzi, że numer nie jest Twój.

search dopasowuje część numeru, jego nazwę lub referencję, ignorując wielkość liter. reference zwraca numery z dokładnie taką referencją, z uwzględnieniem wielkości liter:

Przykład kodu

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

prefix zwraca numery zaczynające się od podanych cyfr, a ich znaczenie zależy od country_code:

Z country_code cyfry są krajowe, dopasowywane zaraz po numerze kierunkowym kraju. prefix=6&country_code=NL zwraca holenderskie numery zaczynające się od +31 6.
Bez country_code cyfry są dopasowywane od początku pełnego numeru. Sam prefix=6 zwraca numery, których numer kierunkowy kraju zaczyna się od 6, na przykład australijskie numery +61, więc nie znajdzie żadnego z Twoich holenderskich numerów komórkowych. Dopasowuje też krótkie numery zaczynające się od tych cyfr.

Nadaj numerowi nazwę i ustaw swoją referencję

Numer posiada dwie własne etykiety. name pozwala odróżniać numery, na przykład Support line. reference przechowuje identyfikator z Twoich własnych danych, na przykład id klienta lub sklepu, i nie musi być unikalny. Oba dotyczą numerów dedykowanych i współdzielonych i mogą mieć do 100 znaków.

Ustaw je za pomocą PATCH /v1/numbers/{number_id}. Pominięte pole zachowuje bieżącą wartość, a pole wysłane jako null jest czyszczone. Początkowe i końcowe białe znaki są usuwane.

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"
  }'

Odpowiedź to 200 ze zaktualizowanym numerem. Aby wyczyścić referencję i zachować nazwę, wyślij referencję jako null i pomiń nazwę:

Przykład kodu

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}'

Aby ustawić referencję podczas zakupu numeru, przekaż reference w POST /v1/numbers/orders. Zamówienie, które musi czekać na operatora, zachowuje referencję do momentu przydzielenia numeru, a numer nosi ją od tego momentu.

Znajdź rekord głosowy, który kieruje numer

Numer obsługujący głos ma dwa identyfikatory. id w GET /v1/numbers zaczyna się od nda_ dla numeru dedykowanego i nal_ dla współdzielonego, i operacje na numerach go przyjmują. Operacje głosowe, w tym ta ustawiająca, dokąd trafiają połączenia przychodzące, przyjmują rekord głosowy numeru, którego id zaczyna się od vnu_. Przekazanie identyfikatora nda_ lub nal_ do operacji głosowej jest odrzucane z 422.

Aby przejść od jednego do drugiego, wyszukaj numery głosowe po numerze telefonu. Wymaga to uprawnienia voice_management na poziomie odczytu:

Przykład kodu

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

id wpisu to identyfikator vnu_, a jego provider.number_id to identyfikator nda_ lub nal_ tego samego numeru. Odbieranie połączeń pokazuje, jak stamtąd skierować numer.

Rekord głosowy ma własne name. Nadanie nazwy numerowi za pomocą PATCH /v1/numbers/{number_id} nie zmienia nazwy rekordu głosowego i odwrotnie.

Zwolnij numer

Możesz zwrócić dedykowany numer na dwa sposoby:

Na koniec opłaconego okresu. DELETE /v1/numbers/{number_id} zatrzymuje odnawianie numeru. Numer działa do końca bieżącego okresu rozliczeniowego i jest wtedy zwalniany. Odpowiedź 202 zwraca numer z releases_at ustawionym na ten moment, a ponowne żądanie zwraca to samo releases_at. Anulowania nie można cofnąć. Numer bez subskrypcji, na przykład przydzielony bez opłaty, jest zwalniany natychmiast, a odpowiedź to 200 z status numeru ustawionym na released.
Teraz. POST /v1/numbers/{number_id}/release zwalnia numer natychmiast, w tym numer już zaplanowany do anulowania. Pozostała część bieżącego okresu nie jest zwracana. Kup i zwolnij numer pokazuje wywołanie w każdym SDK.

Gdy płatność za odnowienie numeru jest zaległa, oba żądania zwracają 409, dopóki nie zostanie opłacona.

Niezależnie od wybranego sposobu zwolnienia wysyłaj żądanie z Idempotency-Key, aby ponowna próba była bezpieczna: ten sam klucz odtwarza pierwszą odpowiedź z nagłówkiem Idempotency-Replay: true, a nowe żądanie dotyczące numeru już zwolnionego zwraca 404 z E01008. Idempotentność wyjaśnia, jak długo klucz jest przechowywany.

Do momentu, gdy zaplanowane anulowanie wejdzie w życie, numer odczytuje się jak zwykle i zawiera releases_at. Po zwolnieniu:

Numer przestaje działać dla Ciebie, a jego subskrypcja nie jest odnawiana.
GET /v1/numbers/{number_id} i rekord głosowy numeru zwracają 404, a numer znika z GET /v1/numbers.
Zamówienie numeru pozostaje w GET /v1/numbers/orders, a jego number_id zwraca teraz 404.
Numer przechodzi w 30-dniowy okres karencji, zanim będzie mógł wrócić do sprzedaży, więc nie możesz od razu kupić tego samego numeru ponownie.

Kolejne kroki

Odbieranie połączeń kieruje numer do trunka SIP, przekierowania lub sekwencji.
Kup i zwolnij numer przeprowadza zakup przez API.
Dokumentacja Numbers API opisuje każdą operację i pole.

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.

Uzyskaj brief wdrożeniowy

Zarządzanie numerami telefonów

Wyświetl wszystkie posiadane numery

Znajdź numer na swojej liście

Nadaj numerowi nazwę i ustaw swoją referencję

Znajdź rekord głosowy, który kieruje numer

Zwolnij numer

Kolejne kroki

Powiązane zasoby