Gerenciando seus números de telefone

Depois que um número é alocado ao seu espaço de trabalho, a API de números permite listar o que você possui, encontrar um número por qualquer um dos seus identificadores, rotulá-lo com um nome e sua própria referência, e cancelar ou liberá-lo quando não precisar mais. A leitura exige uma chave API com o escopo numbers em nível de leitura; alterar, cancelar ou liberar um número exige nível de escrita.

A página Numbers no dashboard mostra os mesmos números.

Liste todos os números que você possui

GET /v1/numbers retorna os números atualmente alocados ao seu espaço de trabalho, do mais recente ao mais antigo, dedicados e compartilhados. Cada página contém 25 números, a menos que você solicite até 100 com limit.

A lista é paginada por cursor. Passe o next_cursor de uma página de volta como starting_after para ler a próxima página, e pare quando next_cursor for null. Os SDKs seguem o cursor automaticamente. Os exemplos abaixo restringem a lista a country_code: "GB"; remova o filtro para percorrer todos os números que você possui:

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

Use o host regional que corresponde ao prefixo bk_{region}_ da sua chave: https://us1.platform.bird.com ou https://eu1.platform.bird.com.

A lista não traz um total. Para contar seus números, percorra as páginas até o fim e conte as entradas. Passar include_total é recusado com 422 e E01029.

Cada entrada traz seu status e ownership. Quando um país não exige documentação de titularidade, ownership é null. A Visão geral de Numbers explica o que cada status significa. Para enviar a documentação que um número está aguardando, consulte Enviar a documentação de titularidade de um número.

Cada entrada também traz pricing, o que a sua organização paga pelo número, líquido de impostos:

recurring_price é a sua tarifa por recurring_period, na moeda em que o número é cobrado. Essa é a sua moeda de cobrança, a menos que a assinatura do número tenha começado antes de uma mudança da sua moeda de cobrança; esse número mantém a moeda da assinatura, indicada por currency_code.
intervals_per_charge é quantos recurring_periods uma renovação cobra. A cobrança recorrente antes de impostos é recurring_price multiplicado por intervals_per_charge. Um preço fixo para o número cobre todo o período, então seu intervals_per_charge é 1.

pricing é null para um número shared e para um número sem assinatura ativa. Quando nenhum preço se aplica à assinatura de um número, seus preços são null com pricing.error: null; fale com vendas para que ele receba um preço. Se o preço não pôde ser lido, pricing.error contém E14009 e os preços são null. Tente novamente GET /v1/numbers/{number_id} com backoff exponencial. O número continua disponível para gerenciamento; não repita uma atualização ou cancelamento já concluído para atualizar o preço.

O dashboard e API usam a mesma resolução de preço. Um preço fixo mantém suas condições existentes; caso contrário, é a tarifa atual, que pode mudar antes da renovação. Ele não informa o que um pedido anterior cobrou. Um número com releases_at definido mantém seu pricing até a liberação, e nenhuma renovação acontece depois.

Encontre um número na sua lista

Os filtros da lista se combinam, então um filtro de país ou capacidade continua valendo junto com os demais.

number busca um número independentemente de como seus registros o escrevem. +31612345678 e 0031612345678 resolvem para o mesmo número. Uma grafia nacional como 0612345678 só resolve quando country_code indica o país:

Exemplo de código

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

Quando você passa um número completo, ou uma grafia nacional com seu country_code, e nenhum outro filtro, um array data vazio significa que o número não está alocado ao seu espaço de trabalho, o que inclui um número que você liberou. Uma grafia nacional sem country_code, como 0612345678 sozinho, também retorna uma lista vazia, então ela não prova que o número não é seu.

search corresponde a parte do número, seu nome ou sua referência, ignorando maiúsculas e minúsculas. reference retorna os números com exatamente aquela referência, diferenciando maiúsculas e minúsculas:

Exemplo de código

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

prefix retorna números que começam com os dígitos informados, e o significado desses dígitos depende de country_code:

Com country_code, os dígitos são nacionais, correspondidos logo após o código de discagem. prefix=6&country_code=NL retorna números holandeses que começam com +31 6.
Sem country_code, os dígitos são correspondidos a partir do início do número completo. prefix=6 sozinho retorna números cujo código de discagem começa com 6, como números australianos +61, então não encontra nenhum dos seus celulares holandeses. Também corresponde a short codes que começam com esses dígitos.

Nomeie um número e defina sua referência

Um número carrega dois rótulos seus. name diferencia seus números, como Support line. reference guarda um identificador dos seus próprios registros, como um id de cliente ou loja, e não precisa ser único. Ambos se aplicam a números dedicados e compartilhados e têm até 100 caracteres.

Defina-os com PATCH /v1/numbers/{number_id}. Um campo que você omitir mantém seu valor atual, e um campo que você enviar como null é limpo. Espaços em branco no início e no final são removidos.

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

A resposta é 200 com o número atualizado. Para limpar a referência e manter o nome, envie a referência como null e omita o nome:

Exemplo de código

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

Para definir a referência ao comprar o número, passe reference em POST /v1/numbers/orders. Um pedido de compra que precisa aguardar a operadora mantém a referência até o número ser alocado, e o número a carrega desse momento em diante.

Encontre o registro de voz que roteia um número

Um número com voz tem dois identificadores. O id em GET /v1/numbers começa com nda_ para um número dedicado e nal_ para um compartilhado, e as operações de números o utilizam. As operações de voz, incluindo a que define para onde vão as chamadas recebidas, utilizam o registro de voz do número, cujo id começa com vnu_. Passar um id nda_ ou nal_ para uma operação de voz é recusado com 422.

Para ir de um ao outro, pesquise os números de voz pelo número de telefone. Isso exige o escopo voice_management no nível de leitura:

Exemplo de código

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

O id da entrada é o identificador vnu_, e o provider.number_id dela é o identificador nda_ ou nal_ do mesmo número. Receber chamadas mostra como rotear o número a partir daí.

O registro de voz tem um name próprio. Nomear um número com PATCH /v1/numbers/{number_id} não altera o nome do registro de voz, e o inverso também vale.

Liberar um número

Você pode devolver um número dedicado de duas formas:

No final do período que você pagou. DELETE /v1/numbers/{number_id} impede a renovação do número. Ele continua funcionando até o período de cobrança atual terminar e é liberado então. A resposta 202 retorna o número com releases_at definido para esse horário, e repetir a solicitação retorna o mesmo releases_at. Um cancelamento não pode ser desfeito. Um número sem assinatura vinculada, como um alocado para você sem cobrança, é liberado imediatamente, e a resposta é 200 com o status do número definido como released.
Agora. POST /v1/numbers/{number_id}/release libera o número imediatamente, incluindo um já agendado para cancelamento. O restante do período atual não é reembolsado. Comprar e liberar um número mostra a chamada em cada SDK.

Enquanto um pagamento de renovação do número estiver em atraso, ambas as solicitações respondem 409 até que ele seja pago.

Qualquer que seja a opção de liberação escolhida, envie a solicitação com um Idempotency-Key para que uma nova tentativa seja segura: a mesma chave reproduz a primeira resposta com um cabeçalho Idempotency-Replay: true, enquanto uma nova solicitação para um número já liberado responde 404 com E01008. Idempotência explica por quanto tempo uma chave é mantida.

Até que um cancelamento agendado entre em vigor, o número é lido normalmente e carrega releases_at. Após a liberação:

O número para de funcionar para você e sua assinatura não é renovada.
GET /v1/numbers/{number_id} e o registro de voz do número respondem 404, e o número sai de GET /v1/numbers.
O pedido do número permanece em GET /v1/numbers/orders, e seu number_id agora responde 404.
O número entra em um período de espera de 30 dias antes de poder voltar à venda, então você não consegue comprar o mesmo número de volta imediatamente.

Próximos passos

Receber chamadas roteia um número para um tronco SIP, um encaminhamento ou uma sequência.
Comprar e liberar um número percorre a compra pela API.
Referência API de Numbers documenta cada operação e campo.

Continue com a documentação, guias e exemplos sobre este tópico.

Obtenha um resumo de implementação

Gerenciando seus números de telefone

Liste todos os números que você possui

Encontre um número na sua lista

Nomeie um número e defina sua referência

Encontre o registro de voz que roteia um número

Liberar um número

Próximos passos

Recursos relacionados