Gestire i numeri di telefono

Una volta che un numero è assegnato al tuo spazio di lavoro, API dei numeri ti permette di elencare quelli in tuo possesso, trovare un numero tramite uno qualsiasi dei suoi identificativi, etichettarlo con un nome e un riferimento personale, e cancellarlo o rilasciarlo quando non ti serve più. La lettura richiede una chiave API con lo scope numbers a livello di lettura; la modifica, la cancellazione o il rilascio di un numero richiedono il livello di scrittura.

La pagina Numbers nella dashboard mostra gli stessi numeri.

Elencare tutti i numeri in tuo possesso

GET /v1/numbers restituisce i numeri attualmente assegnati al tuo spazio di lavoro, dal più recente, dedicati e condivisi. Ogni pagina contiene 25 numeri, a meno che tu non ne richieda fino a 100 con limit.

La lista è paginata tramite cursore. Passa il next_cursor di una pagina come starting_after per leggere la pagina successiva, e fermati quando next_cursor è null. Gli SDK seguono il cursore automaticamente. Gli esempi qui sotto restringono la lista a country_code: "GB"; ometti il filtro per scorrere tutti i numeri in tuo possesso:

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

Usa l'host regionale corrispondente al prefisso bk_{region}_ della tua chiave: https://us1.platform.bird.com o https://eu1.platform.bird.com.

La lista non include un totale. Per contare i tuoi numeri, scorri le pagine fino alla fine e conta le voci. Passare include_total viene rifiutato con 422 e E01029.

Ogni voce contiene il proprio status e ownership. Quando un paese non richiede documentazione di proprietà, ownership è null. La panoramica Numbers spiega il significato di ogni stato. Per presentare la documentazione che un numero attende, consulta Presentare la documentazione di proprietà di un numero.

Ogni voce contiene anche pricing, quanto la tua organizzazione paga per il numero, al netto delle imposte:

• recurring_price è la tua tariffa per recurring_period, nella valuta in cui viene addebitato il numero. Si tratta della tua valuta di fatturazione, a meno che l'abbonamento del numero non sia iniziato prima di un cambio della tua valuta di fatturazione; in quel caso il numero mantiene la valuta del proprio abbonamento, indicata da currency_code.
• intervals_per_charge indica quanti recurring_period addebita un rinnovo. L'addebito ricorrente al netto delle imposte è recurring_price moltiplicato per intervals_per_charge. Un prezzo fisso per il numero copre l'intero periodo, quindi il suo intervals_per_charge è 1.

pricing è null per un numero shared e per un numero senza un abbonamento attivo. Quando all'abbonamento di un numero non si applica alcun prezzo, i suoi prezzi sono null con pricing.error: null; contatta il team commerciale per ottenerne il prezzo. Se non è stato possibile leggere il prezzo, pricing.error contiene E14009 e i prezzi sono null. Riprova GET /v1/numbers/{number_id} con backoff esponenziale. Il numero resta disponibile per la gestione; non ripetere un aggiornamento o una cancellazione già completati per aggiornarne il prezzo.

La dashboard e API usano la stessa risoluzione del prezzo. Un prezzo fisso mantiene le condizioni esistenti; altrimenti si tratta della tariffa corrente, che può cambiare prima del rinnovo. Non riporta quanto ha addebitato un ordine precedente. Un numero con releases_at impostato mantiene il suo pricing fino al rilascio, e nessun rinnovo segue.

Trovare un numero nella propria lista

I filtri della lista si combinano, quindi un filtro per paese o funzionalità resta attivo insieme agli altri.

number cerca un numero indipendentemente da come è scritto nei tuoi record. +31612345678 e 0031612345678 puntano allo stesso numero. Un formato nazionale come 0612345678 viene risolto solo quando country_code indica il paese:

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

Quando passi un numero completo, o un formato nazionale con il relativo country_code, senza altri filtri, un array data vuoto significa che il numero non è assegnato al tuo spazio di lavoro, incluso un numero che hai rilasciato. Un formato nazionale senza country_code, ad esempio 0612345678 da solo, restituisce anch'esso una lista vuota, quindi non dimostra che il numero non sia tuo.

search cerca una corrispondenza parziale nel numero, nel nome o nel riferimento, ignorando maiuscole e minuscole. reference restituisce i numeri con esattamente quel riferimento, rispettando maiuscole e minuscole:

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

prefix restituisce i numeri che iniziano con le cifre indicate, e il significato di quelle cifre dipende da country_code:

• Con country_code, le cifre sono nazionali, confrontate subito dopo il prefisso internazionale. prefix=6&country_code=NL restituisce i numeri olandesi che iniziano con +31 6.
• Senza country_code, le cifre sono confrontate dall'inizio del numero completo. prefix=6 da solo restituisce i numeri il cui prefisso internazionale inizia con 6, come i numeri australiani +61, quindi non trova nessuno dei tuoi numeri mobili olandesi. Corrisponde anche agli short code che iniziano con quelle cifre.

Assegnare un nome a un numero e impostare il proprio riferimento

Un numero porta due etichette personalizzate. name distingue i tuoi numeri, ad esempio Support line. reference contiene un identificatore dai tuoi record, come un id cliente o negozio, e non deve essere univoco. Entrambi si applicano a numeri dedicati e condivisi e possono contenere fino a 100 caratteri.

Impostali con PATCH /v1/numbers/{number_id}. Un campo che ometti mantiene il valore corrente, e un campo che invii come null viene cancellato. Gli spazi iniziali e finali vengono rimossi.

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

La risposta è 200 con il numero aggiornato. Per cancellare il riferimento e mantenere il nome, invia il riferimento come null e ometti il nome:

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

Per impostare il riferimento al momento dell'acquisto del numero, passa reference su POST /v1/numbers/orders. Un ordine che deve attendere un operatore conserva il riferimento fino all'assegnazione del numero, e da quel momento il numero lo mantiene.

Trovare il record vocale che instrada un numero

Un numero con funzionalità vocale ha due identificatori. L'id su GET /v1/numbers inizia con nda_ per un numero dedicato e nal_ per uno condiviso, ed è quello accettato dalle operazioni sui numeri. Le operazioni vocali, compresa quella che imposta dove vanno le chiamate in entrata, accettano il record vocale del numero, il cui id inizia con vnu_. Passare un id nda_ o nal_ a un'operazione vocale viene rifiutato con 422.

Per passare da uno all'altro, cerca i numeri vocali in base al numero di telefono. Serve lo scope voice_management a livello di lettura:

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

L'id dell'elemento è l'identificatore vnu_, e il suo provider.number_id è l'identificatore nda_ o nal_ dello stesso numero. Ricevere chiamate mostra come instradare il numero da lì.

Il record vocale ha un name proprio. Assegnare un nome a un numero con PATCH /v1/numbers/{number_id} non modifica il nome del record vocale, e vale anche il contrario.

Rilasciare un numero

Puoi restituire un numero dedicato in due modi:

• Alla fine del periodo già pagato. DELETE /v1/numbers/{number_id} impedisce il rinnovo del numero. Il numero continua a funzionare fino alla fine del periodo di fatturazione corrente e viene rilasciato a quel punto. La risposta 202 restituisce il numero con releases_at impostato su quel momento, e una nuova richiesta restituisce lo stesso releases_at. Una cancellazione non può essere annullata. Un numero senza abbonamento associato, ad esempio uno assegnato senza addebito, viene rilasciato immediatamente e la risposta è 200 con status del numero impostato su released.
• Subito. POST /v1/numbers/{number_id}/release rilascia il numero immediatamente, anche se già programmato per la cancellazione. Il resto del periodo corrente non viene rimborsato. Acquistare e rilasciare un numero mostra la chiamata in ogni SDK.

Mentre un pagamento di rinnovo per il numero è scaduto, entrambe le richieste rispondono 409 fino al saldo.

Qualunque opzione di rilascio tu scelga, invia la richiesta con un Idempotency-Key così che un nuovo tentativo sia sicuro: la stessa chiave riproduce la prima risposta con un header Idempotency-Replay: true, mentre una nuova richiesta per un numero già rilasciato risponde 404 con E01008. Idempotenza spiega per quanto tempo una chiave viene conservata.

Fino a quando una cancellazione programmata non ha effetto, il numero si legge normalmente e porta releases_at. Dopo il rilascio:

• Il numero smette di funzionare per te e il suo abbonamento non si rinnova.
• GET /v1/numbers/{number_id} e il record vocale del numero rispondono 404, e il numero esce da GET /v1/numbers.
• L'ordine del numero resta in GET /v1/numbers/orders, e il suo number_id ora risponde 404.
• Il numero entra in un periodo di attesa di 30 giorni prima di poter tornare in vendita, quindi non puoi riacquistare lo stesso numero immediatamente.

Passaggi successivi

• Ricevere chiamate instrada un numero verso un trunk SIP, un inoltro o una sequenza.
• Acquistare e rilasciare un numero guida l'acquisto tramite la API.
• Il riferimento API Numbers documenta ogni operazione e campo.