Migrar do Telserv para o Bird

Este guia é para integrações que chamam a API de parceiro Telserv, V1 ou V2, para comprar, rotear e liberar números, e que agora migram para a Bird API.

A Bird API atende todos os produtos Bird, então suas operações de números e voz seguem as convenções do próprio Bird em vez das do Telserv. A maioria das funcionalidades que sua integração usa tem uma chamada Bird correspondente. Os endpoints, payloads, identificadores e autenticação são diferentes, então planeje reescrever a integração. Onde o Bird faz uma tarefa de forma diferente, este guia mostra como.

Este guia é um trabalho em andamento. Ele cobre o que o Bird faz e cresce conforme a migração avança. Se uma operação do Telserv que você usa não está listada aqui, ela ainda precisa de escopo e desenvolvimento antes de ser adicionada; pergunte ao seu contato de migração sobre ela.

Antes de começar

• Uma organização Bird com verificação de identidade concluída, que a primeira compra de número exige.
• Uma chave API com os escopos que as receitas usam: numbers em nível de escrita para números e pedidos, compliance em nível de escrita para as operações avulsas de documentação de titularidade, e voice_management em nível de escrita para trunks SIP, números de voz e números verificados. A chamada de teste também precisa de voice:write, e a leitura de legs de chamada precisa de voice:read.
• Saldo da carteira. Os pedidos são pagos com a carteira. Quando um pedido é recusado explica as recusas 402 e 412.

Os números que sua integração gerencia no Telserv não precisam ser comprados novamente. Quando seus números forem movidos para o seu espaço de trabalho Bird, eles aparecem em GET /v1/numbers. Seu contato de migração confirma quando isso acontece. Para obter o identificador nda_ de um número migrado, consulte-o com GET /v1/numbers?number=<digits>, informando os dígitos com o código do país, e guarde o id como NUMBER_ID.

Os exemplos leem sua chave de BIRD_API_KEY e seu host regional de BIRD_API_URL: https://eu1.platform.bird.com para uma chave bk_eu1_, ou https://us1.platform.bird.com para uma chave bk_us1_. As outras variáveis, como TRUNK_ID e NUMBER_ID, guardam um identificador de uma resposta anterior; cada passo nomeia a que ele define.

O que muda no contrato

A Bird API recusa um parâmetro de consulta que não reconhece com 422 e E01029. Remova filtros exclusivos do Telserv, como city, das suas solicitações em vez de enviá-los.

Dois identificadores para um número

Um número com capacidade de voz alocado ao seu espaço de trabalho tem dois registros, cada um com seu próprio identificador:

• A alocação, retornada por GET /v1/numbers. Seu id começa com nda_ para um número dedicado e com nal_ para um compartilhado, e o number_id de um pedido é o identificador nda_ do número comprado. Use-a para ler, nomear e referenciar o número, e para liberar um número dedicado.
• O registro de voz, vnu_, retornado por GET /v1/voice/numbers. Use-o para ler e alterar para onde vão as chamadas recebidas do número. Um número sem capacidade de voz, como um número apenas de SMS, não tem registro de voz.

As operações de voz recusam um identificador nda_ ou nal_ com 422. Para encontrar o registro de voz de um número, liste os números de voz com search definido como os dígitos do número e pegue a entrada cujo provider.number_id é igual ao id da alocação. Rotear um número para o seu trunk SIP mostra a solicitação, e Gerenciando seus números de telefone cobre a consulta.

O GET /numbers/{dnisId} do Telserv se torna duas leituras no Bird: a alocação para status e documentação de titularidade, e o registro de voz para a rota.

Mapear operações do Telserv para Bird

Cada tabela lista uma tarefa, a chamada do Telserv que a executava e a chamada Bird que a executa agora. As notas abaixo de cada tabela cobrem o que muda na solicitação ou na resposta.

Loja

• Pesquisa. country_code é obrigatório, então uma pesquisa cobre um país. prefix recebe os dígitos nacionais após o código do país: o prefix=3170 do Telserv se torna country_code=NL&prefix=70. Filtre por código de área com prefix no lugar de city, e por number_type e capabilities no lugar de productId.
• Documentação nos resultados de pesquisa. Cada resultado traz ownership_registration_required no lugar do filtro excludeNumbersRequireVerification. Um valor true significa que o número é cobrado a partir da compra, mas não envia SMS nem transporta chamadas de voz de entrada ou saída até que sua documentação seja aprovada.
• Consultar um número. Ele é endereçado pelo seu número E.164.
• Preços. O Telserv retornava pricing.staticPricing nas leituras detalhadas de um número e de um produto. Na Bird, cada resultado de pesquisa traz o preço para a sua organização em pricing: setup_price no lugar de nrc, e recurring_price por recurring_period no lugar de mrc, com intervals_per_charge indicando quantos períodos uma cobrança abrange. Pesquisar e comprar um número com sua referência descreve os campos de preço.
• Compra. Envie number e um reference opcional. O pedido é pago com a sua carteira. A maioria dos pedidos responde 201; um pedido que aguarda uma operadora responde 202, e você consulta o pedido periodicamente.
• Reservar. Fazer o pedido do número o reserva. Verifique um candidato primeiro e depois faça o pedido.

Números

• Listar. A lista contém os números alocados a você agora. Um número liberado que você comprou via Bird permanece visível pelo seu pedido em GET /v1/numbers/orders. Reconcilie seus números mapeia os filtros.
• Ler. Status, documentação de titularidade e preço estão na alocação, e a rota está no registro de voz. O objeto pricing da alocação, com recurring_price por recurring_period e intervals_per_charge, substitui pricing.staticPricing.mrc, e a lista também o inclui, ao contrário do GET /numbers do Telserv.
• Alterar. name e reference estão na alocação, e a rota está no registro de voz. Defina um codec forçado e um limite de chamadas simultâneas no seu equipamento SIP. destinationDistributionType passa a ser priority do gateway no trunk SIP: FailOver atribui a cada gateway um priority diferente, e RoundRobin atribui o mesmo a todos.
• Liberar. DELETE mantém o número até o fim do período já pago e o libera depois. POST …/release o libera imediatamente. Nenhum dos dois aceita uma data. Liberar um número mostra ambas as solicitações.

Destinos e perfis

• Equipamento SIP. Um gateway pertence ao trunk e atende cada número roteado para ele, então números que precisam de listas de destino diferentes precisam de trunks diferentes. sortOrder passa a ser priority. Aplique tempo de toque e janelas de horário no seu equipamento SIP.
• Encaminhar. Defina forward_to e forward_as. forward_to deve ser um dos seus números verificados; um número não verificado responde 412 com E21053. forward_as escolhe qual número a chamada encaminhada exibe como identificador de chamadas. Um número tem apenas uma rota por vez, então para fazer fallback do equipamento SIP para um número de telefone, encaminhe a chamada a partir do seu equipamento SIP.
• Parar de receber chamadas. O número rejeita chamadas até que você o roteie novamente. Para manter um padrão fixo no lugar de um perfil padrão, roteie o número para um trunk que contenha seus gateways padrão.
• Perfis. distributionType passa a ser priority: FailOver atribui a cada gateway um priority diferente, e RoundRobin atribui o mesmo a todos. A distribuição é definida por trunk, então números que precisam de distribuição diferente precisam de trunks diferentes. O placeholder {dnis} passa a ser {number} em destination_format, e um prefixCLIP passa a ser o texto antes de {number} em origination_format.
• Aplicar um perfil. Um trunk é endereçado pelo seu identificador spt_, enquanto no Telserv o perfil era endereçado pelo nome.

Documentos e dados do usuário final

• Requisitos. O catálogo de condições do Telserv cobria todos os produtos de uma vez; o Bird lê um formulário por vez. Solicite os requisitos de um número com subject_kind=number, seu identificador nda_ como subject_id e seu country_code, ou leia um formulário antes de comprar com program definido como o tipo de número e sem subject_id. Cada entrada em fields substitui uma condição ou um rótulo de usuário final do Telserv: seu key é a chave sob a qual você responde, e data_type document marca uma entrada que exige um arquivo.
• Documentos. Envie o arquivo como multipart/form-data no lugar de um fileContent em base64; Enviar cada documento lista os arquivos aceitos. Enviar o mesmo arquivo duas vezes retorna o mesmo anexo. O upload sozinho não registra nada: quem registra é a submissão que cita o attachment_id dele.
• Dados do usuário final e documentos juntos. O Telserv recebia cada documento em uma chamada própria, e os dados do usuário final como uma lista de rótulos em outra. O Bird recebe todas as respostas, digitadas e de documento, em uma única submissão, e não há rascunhos: a solicitação envia as respostas para revisão. Depois, acompanhe ownership.next, que indica reenvio para correções e uma nova submissão apenas quando necessária (Enviar todas as respostas).
• Substituições. Envie apenas as respostas que você substitui, e as demais mantêm sua revisão. O Telserv aceitava um novo arquivo para uma condição enquanto o número aguardava verificação, e o arquivo reiniciava a revisão dessa condição; o Bird substitui uma resposta rejeitada, expirada ou ainda não fornecida, e recusa uma ainda em revisão ou já aceita, exceto uma resposta marcada como editable_for_verifier_repair enquanto uma correção solicitada por nós estiver aberta (Corrigir uma resposta rejeitada).
• Andamento. ownership.status e ownership.next informam a situação do número. Cada resposta tem seu próprio state, e uma resposta rejeitada traz o reason do revisor. O Bird também envia cada resultado por e-mail aos proprietários da sua organização e à pessoa que enviou ou corrigiu a submissão por último. ownership costuma ser null quando o número não exige documentação.

Enviar a documentação de titularidade mostra as solicitações, e Enviar a documentação de titularidade de um número cobre o fluxo completo, incluindo o envio pelo painel e junto com o pedido.

Produtos e dados mestres

Cada resultado de pesquisa descreve seu produto com number_type, capabilities e ownership_registration_required, e traz o preço para a sua organização no lugar do pricing.staticPricing do produto (nrc e mrc). Os preços padrão do Bird estão na página de preços de números de telefone. O sessionPricing por minuto do Telserv não tem equivalente nessas leituras; as tarifas de voz estão na página de preços de voz.

Os tipos de número do Telserv correspondem ao number_type do Bird assim:

O que funciona de forma diferente

Estas tarefas do Telserv são feitas de forma diferente no Bird. Planeje-as antes de migrar uma integração que dependa de alguma delas.

• Documentação. Envie os documentos e os dados do usuário final de um número em uma única submissão, sem rascunhos, e corrija respostas rejeitadas com reenvio.
• Reservas. Faça o pedido do número quando tiver escolhido; o pedido já o reserva.
• Configurações de chamada por número. Aplique um codec forçado, um limite de chamadas simultâneas, tempo de toque e janelas de horário no seu equipamento SIP.
• Data de liberação. Bird libera um número no fim do período já pago ou imediatamente, não em uma data que você escolhe. Mantenha do seu lado as datas de cancelamento que você enviou ao Telserv e execute cada uma quando ela chegar.
• Saldo da carteira. Consulte o saldo e faça recarga no painel.

Pesquisar e comprar um número com sua referência

Pesquise um país. Combine number_type, capabilities e prefix para refinar os resultados:

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

Cada resultado traz um objeto pricing com o preço que sua organização paga pelo número, líquido de impostos e na sua moeda de cobrança, com quaisquer preços que você combinou com Bird aplicados:

• setup_price é cobrado uma vez quando você faz o pedido do número. Uma taxa publicada de zero tem um amount de "0". O próprio campo é null quando não há taxa de ativação e também sempre que recurring_price é null, porque esse número não pode ser pedido.
• recurring_price é a tarifa por recurring_period.
• intervals_per_charge indica quantos recurring_periods uma cobrança abrange. A cobrança recorrente antes de impostos é recurring_price multiplicado por intervals_per_charge, cobrada quando o número é atribuído ao seu espaço de trabalho e a cada renovação; a taxa de ativação é separada. Para um pedido que aguarda uma operadora, a atribuição acontece quando o pedido é concluído.

A referência do API mostra um exemplo de resultado. Um resultado com pricing.recurring_price: null não informa um preço recorrente. Fale com vendas para obter um preço para esse país e tipo de número antes de fazer o pedido.

O painel e API usam o mesmo preço da organização, incluindo a conversão para a sua moeda de cobrança. Uma leitura de preço não trava uma cotação: mudanças de tarifa ou de câmbio antes de uma cobrança posterior podem alterar o valor dela. Se a consulta falhar, a pesquisa retorna 503 com E14009. Tente novamente a leitura com backoff exponencial; uma falha na consulta nunca significa que o número não custa nada.

Para confirmar um candidato e seu preço antes de comprá-lo, leia-o com GET /v1/numbers/available/{number}. Um 404 significa que ele não está mais à venda.

Faça o pedido do número com a referência que você usava no Telserv e escolha uma chave de idempotência que você guarda para qualquer nova tentativa desta compra:

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

Uma resposta 201 tem status: completed e um number_id, o identificador nda_ do número. Guarde-o como NUMBER_ID. Uma resposta 202 significa que o pedido aguarda uma operadora: consulte o pedido até que seu status seja completed ou failed. Uma taxa de ativação já cobrada não é reembolsada se o pedido falhar depois. A referência é definida no número quando o pedido é concluído. Ela comporta até 100 caracteres e não precisa ser única.

Tentar novamente um pedido de um número que seu espaço de trabalho tem alocado retorna o pedido existente, então uma nova tentativa não cobra duas vezes. Comprar e liberar um número explica as recusas.

Para definir ou alterar uma referência depois, envie reference (e opcionalmente name) para PATCH /v1/numbers/{number_id}. Envie null para limpar um campo.

Verificar se um número pode realizar chamadas

Um número cujo status é pending_ownership_registration está alocado e é cobrado, mas não envia SMS e rejeita chamadas de voz de entrada e saída até que a documentação de titularidade seja aprovada. Antes de rotear um número ou fazer uma chamada de teste para ele, leia-o com GET /v1/numbers/{number_id} e verifique se status é active. Se estiver pendente, envie a documentação de titularidade. O status de um número alocado explica cada valor.

Os exemplos abaixo usam um número móvel holandês. Verifique o status do seu próprio número da mesma forma, independentemente do país.

Enviar a documentação de titularidade

O Telserv recebia a documentação de um número com um POST /numbers/{dnisId}/documents por documento e um POST /numbers/{dnisId}/enduserdata para todos os rótulos. O Bird recebe ambos em uma única submissão, depois que você faz o upload dos documentos.

1. Leia o country_code do número e guarde-o como COUNTRY_CODE. O comando o extrai com jq; se você não usa jq, leia-o manualmente:

   Exemplo de código

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

2. Leia o que o país do número exige. Cada entrada em fields tem o key sob o qual você responde, um data_type e required, que indica se a resposta é obrigatória. Guarde o program indicado na resposta como PROGRAM:

   Exemplo de código

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

   Um 422 com E19001 significa que não há formulário de titularidade para esse país.

3. Faça o upload de cada documento que um campo document exige, como arquivo em vez de fileContent em base64. Guarde o id da resposta, o identificador tca_ do anexo, como ATTACHMENT_ID:

   Exemplo de código

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

4. Envie todas as respostas de uma vez: uma entrada para cada campo cujo required é true e para cada campo opcional para o qual você tem uma resposta real, com os dados do usuário final como value e cada documento como attachment_id. Omita um campo opcional em vez de inventar um valor para ele. O exemplo mostra duas respostas; adicione as demais obrigatórias antes de enviar. Esta solicitação envia as respostas para análise. Guarde o id da resposta, o identificador csb_ da submissão, como SUBMISSION_ID:

   Exemplo de código

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

   Uma resposta 201 retorna a submissão. Um 422 não envia nada: corrija o corpo e envie-o com uma nova chave de idempotência, porque a chave reproduz a recusa. Enviar todas as respostas explica cada recusa.

5. Quando um analista rejeitar uma resposta, substitua apenas essa resposta, como descreve Corrigir uma resposta rejeitada:

   Exemplo de código

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

Para enviar a documentação durante a compra, envie o mesmo answers no bloco compliance de POST /v1/numbers/orders. Esse pedido usa o escopo numbers existente em nível de escrita, inclusive quando inclui documentação.

Acompanhe a análise com ownership.status em GET /v1/numbers/{number_id}. As respostas são uma declaração legal feita em nome da sua empresa, então envie apenas respostas que alguém responsável por elas tenha confirmado. Enviar a documentação de titularidade de um número explica cada solicitação, a análise e o envio junto com o pedido.

Rotear um número para o seu trunk SIP

Um número novo não tem rota própria, então segue a rota padrão do seu espaço de trabalho. Essa rota padrão começa como reject, mas em um espaço de trabalho que já definiu uma, o número novo atende as chamadas por ela assim que é alocado. Para entregar as chamadas dele ao seu equipamento, crie um trunk SIP com chamadas de entrada ativadas, adicione um gateway e aponte o número para o trunk. Trunks SIP explica como conectar seu equipamento ao trunk.

1. Crie o trunk com chamadas de entrada ativadas. Guarde o id da resposta, o identificador spt_ do trunk, como TRUNK_ID:

   Exemplo de código

   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. Adicione um gateway. Por padrão, o gateway recebe os números discado e chamador em E.164 com o +. Se o seu equipamento espera números sem o +, como o placeholder {dnis} do Telserv fazia, defina destination_format para o número discado e origination_format para o número chamador como {number}:

   Exemplo de código

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

   Para failover, adicione um segundo gateway; O que um gateway precisa explica priority e os formatos de número. Criar o mesmo gateway novamente sem uma chave de idempotência responde 409 com E21047.

3. Encontre o registro de voz do número. Pesquise com os dígitos do número e pegue o id da entrada cujo provider.number_id é o id da alocação. Guarde-o como VOICE_NUMBER_ID:

   Exemplo de código

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

4. Aponte o número para o trunk:

   Exemplo de código

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

   Uma resposta 200 mostra a nova rota. Um trunk com chamadas de entrada desativadas responde 412 com E21052.

Desativar chamadas de entrada em um trunk, ou excluir o trunk, devolve cada número roteado para ele à rota padrão do seu espaço de trabalho, e reativar não restaura essas rotas. Entregar chamadas a um trunk SIP explica isso e as rotas trunk, forward e reject.

Reconciliar seus números

Percorra a lista com o maior tamanho de página. Passe o next_cursor de cada página como NEXT_CURSOR para ler a próxima página, até que next_cursor seja null. A lista não retorna uma contagem total.

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"

Os filtros de lista do Telserv mapeiam para os de Bird assim:

Encontre um número na sua lista cobre cada filtro em detalhe.

Cada entrada traz pricing, com recurring_price por recurring_period e intervals_per_charge. A menos que um preço esteja fixo para o número, recurring_price é a tarifa atual da sua organização, e cada renovação cobra a tarifa vigente no momento da renovação, de modo que uma cobrança já faturada pode diferir dela. Liste todos os números que você possui explica em qual moeda cada número é cobrado, quando pricing ou seus preços são null e o que fazer quando pricing.error está definido.

Um número liberado sai dessa lista, e lê-lo pelo number_id responde 404. Se você o comprou em Bird, o pedido concluído permanece em GET /v1/numbers/orders.

Liberar um número

As duas solicitações se aplicam a um número dedicado, pelo seu identificador nda_; um número compartilhado é recusado com E14002. Para manter o número até o fim do período que você já pagou, cancele-o:

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

Uma resposta 202 retorna o número com releases_at, o fim do período pago. O número mantém seu status atual até lá, sua assinatura não é renovada e ele é liberado nesse momento. Solicitar novamente retorna o mesmo releases_at, e um cancelamento não pode ser desfeito. Um número sem assinatura por trás é liberado imediatamente, e a resposta é 200 com o status do número definido como released.

Para liberar o número agora, incluindo um já agendado para cancelamento:

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

Uma resposta 204 significa que o número foi liberado, com efeito imediato. O restante do período atual não é reembolsado.

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

Nenhuma das solicitações aceita uma data, então mantenha o cronograma que você enviou ao Telserv como requestedCancelDate do seu lado. Para manter um número até a data dele, cancele-o quando a data estiver dentro do período de cobrança atual: ele é liberado quando esse período termina, na data ou depois dela. Para liberá-lo exatamente na data, libere-o nesse dia. Liberar um número explica o que cada solicitação faz com o número, suas cobranças e uma nova tentativa.

Fazer uma chamada de teste para o seu número

Para verificar uma rota de ponta a ponta, faça uma chamada para o número a partir de outro número que seu espaço de trabalho possa apresentar como identificador de chamadas. O país do número precisa estar habilitado nos seus destinos de voz, ou a chamada não é completada. A solicitação abaixo executa uma sequência inline que desliga assim que a chamada é atendida, então nenhuma sequência salva é necessária. Ela faz uma chamada real, e as tarifas normais de chamada se aplicam.

Salve a solicitação como test-call.json. Coloque o identificador de chamadas que você apresenta em from, um número verificado ou de propriedade do seu espaço de trabalho, e o número em teste em to:

{
  "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": {}
  }
}

Envie:

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

Defina TEST_CALL_KEY com um valor novo para cada teste e reutilize-o ao tentar novamente o mesmo teste após um timeout ou resultado inconclusivo: a mesma chave e solicitação dentro de três horas reproduzem a primeira aceitação em vez de realizar uma segunda chamada. Uma resposta 202 aceita a chamada e retorna seu initial_leg_id. A aceitação não prova que a chamada foi conectada: leia o leg com GET /v1/voice/legs/{leg_id}, ou liste os legs realizados para o número com GET /v1/voice/legs e seu filtro to, e verifique se seu equipamento recebeu a chamada. Criar uma chamada de voz cobre os requisitos de identificador de chamadas e destino e as regras de nova tentativa.

Próximos passos

• Comprar e liberar um número
• Gerenciando seus números de telefone
• Enviar a documentação de titularidade de um número
• Recebendo chamadas
• Trunks SIP
• Idempotência