Receber chamadas

Um número que seu espaço de trabalho possui pode entregar uma chamada recebida a um trunk SIP, encaminhá-la para um número verificado, executar uma sequência publicada ou rejeitá-la. Cada número tem uma rota por vez: a sua própria, ou a rota padrão do espaço de trabalho quando não tem nenhuma.

A rota padrão do espaço de trabalho começa como rejeitar, então um número que ninguém configurou recusa os chamadores em vez de ficar sem resposta nenhuma. Altere o padrão para dar a todos esses números a mesma resposta. Veja Definir uma rota padrão.

Para tratar chamadas recebidas em um fluxo nativo do Bird, publique uma sequência e vincule o número à entrada de chamada dela. A entrada selecionada deve aceitar dados vazios.

Pré-requisitos

Antes de apontar um número para uma resposta:

• Um número que pode receber chamadas. Abra Voice > Numbers e verifique a coluna Directions em busca de uma marcação de entrada. Um número que você registrou como caller ID de outra operadora não recebe chamadas aqui: essa operadora roteia as chamadas feitas para ele, então ele não carrega nenhuma resposta.
• Para entrega a um trunk: um trunk SIP com chamadas de entrada ativadas e pelo menos um gateway de entrega.
• Para um encaminhamento: um caller ID verificado para encaminhar.
• Para uma sequência: uma sequência ativa e publicada no mesmo espaço de trabalho, com uma entrada de chamada que aceita dados de entrada vazios. Em Inbound routing, selecione Run a sequence, escolha a sequência e a entrada de chamada, e salve. O guia do construtor de sequências explica publicação e testadores de rascunho para chamadas recebidas.
• Para alterar a configuração pela API ou CLI: uma chave API com o escopo voice_management em nível de escrita. Esse escopo cobre a configuração de voz; o escopo voice cobre tráfego de chamadas e estatísticas, então a leitura do registro de chamadas precisa do outro.

Entregar chamadas a um trunk SIP

A entrega disca para o seu próprio sistema telefônico nos endereços que você declara no trunk. Ative a direção primeiro, porque um número só pode ser apontado para um trunk que já aceita chamadas de entrada.

1. Abra Voice > SIP Trunks, abra o trunk e, em Inbound calling, selecione Enable inbound.
2. Adicione pelo menos um gateway na mesma seção. Um trunk sem gateway recusa todas as chamadas recebidas nos números que ele atende.
3. Abra Voice > Numbers, abra o número e, em Inbound routing, escolha Deliver to a SIP trunk.
4. Escolha o trunk e selecione Save. Apenas trunks com chamadas de entrada ativadas aparecem na lista.

A coluna Used for na lista de Numbers passa a mostrar o número como entregue a esse trunk, e a página do próprio trunk lista os números que ele atende.

Pela API, atualize o trunk com inbound_enabled: true, adicione um gateway e aponte o registro de voz do número para o trunk. O registro de voz tem um ID que começa com vnu_, que difere do ID nda_ que /v1/numbers retorna para o mesmo número. Passar o ID nda_ a uma operação de número de voz é recusado com 422. Para encontrar o registro de voz, pesquise seus números de voz pelos dígitos do número:

for await (const number of bird.voice.numbers.list({ search: "31201234567" })) {
  console.log(number.id, number.phone_number);
}

for number, err := range client.Voice.Numbers.List(context.Background(), bird.VoiceNumbersListParams{
	Search: "31201234567",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(number.Id, number.PhoneNumber)
}

foreach ($bird->voice->numbers->list(['search' => '31201234567']) as $number) {
    echo $number->getId(), ' ', $number->getPhoneNumber(), "\n";
}

bird voice numbers list --search 31201234567

curl -X GET "https://{region}.platform.bird.com/v1/voice/numbers" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "search=31201234567"

Cada resultado carrega seu id, seu phone_number e a inbound_configuration.route atual. Envie a rota de trunk para atualizar o número de voz com esse id:

const number = await bird.voice.numbers.update("NUMBER_ID", {
  inbound_configuration: {
    route: { type: "trunk", trunk_id: "spt_01krdgeqcxet5s7t44vh8rt9mg" },
  },
});
console.log(number.id, number.inbound_configuration?.route?.type);

var route bird.VoiceCallRouteWritable
if err := route.FromVoiceCallRouteTrunk(bird.VoiceCallRouteTrunk{
	TrunkId: "spt_01krdgeqcxet5s7t44vh8rt9mg",
}); err != nil {
	log.Fatal(err)
}
number, err := client.Voice.Numbers.Update(context.Background(), "NUMBER_ID", bird.VoiceNumbersUpdateParams{
	InboundConfiguration: &bird.VoiceInboundConfigurationPut{Route: route},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(number.Id)

$number = $bird->voice->numbers->update(
    'NUMBER_ID',
    (new VoiceNumberUpdate())->setInboundConfiguration(
        (new VoiceInboundConfigurationPut())->setRoute([
            'type' => 'trunk',
            'trunk_id' => 'spt_01krdgeqcxet5s7t44vh8rt9mg',
        ]),
    ),
);
echo $number->getId(), "\n";

bird voice numbers update <number-id> --body-file - <<'JSON'
{
  "inbound_configuration": {
    "route": {
      "type": "trunk",
      "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
    }
  }
}
JSON

curl -X PATCH "https://{region}.platform.bird.com/v1/voice/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_configuration": {
      "route": {
        "type": "trunk",
        "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  }'

Um trunk com chamadas de entrada desativadas é recusado com 412 e E21052. A rota substitui o que o número tinha antes. Enviar {"type": "reject"} como rota recusa os chamadores independentemente do padrão, e enviar null retorna o número à rota padrão do espaço de trabalho.

O que um gateway precisa

Um gateway é um endereço para o qual uma chamada é entregue, e como esse par quer que os dois números da chamada sejam escritos:

Gateways com a mesma prioridade dividem as chamadas igualmente, e qualquer um deles pode ser tentado primeiro em uma chamada. Para transferir a entrega a um segundo endereço, atribua a esse gateway um número de prioridade maior: ele é tentado quando o primeiro não atende.

Ambos os formatos de número são templates sobre um placeholder, {number}, que representa o número sem o + inicial. O formato de destino é colocado antes do host da URI SIP, então 1234#{number} entrega uma chamada para +31201234567 como sip:1234#31201234567@pbx.example.com:5060. O padrão para ambos é +{number}, que é E.164. Um formato que não contém nenhum {number} envia todos os números que o trunk atende para um único endereço fixo. Um par que espera números sem o + usa {number} sozinho como formato.

Pela API, adicione um gateway ao trunk com essas configurações. Ative as chamadas de entrada do trunk primeiro: criar um gateway em um trunk sem isso é recusado com 412 e E21052.

const gateway = await bird.voice.trunks.gateways.create("TRUNK_ID", {
  sip_uri: "sip:pbx.example.com:5060",
  priority: 0,
  destination_format: "1234#{number}",
});
console.log(gateway.id, gateway.priority);

gateway = client.voice.trunks.gateways.create(
    "TRUNK_ID",
    sip_uri="sip:pbx.example.com:5060",
    priority=0,
    destination_format="1234#{number}",
)
print(gateway.id, gateway.priority)

gateway, err := client.Voice.Trunks.Gateways.Create(context.Background(), "TRUNK_ID", bird.VoiceTrunksGatewaysCreateParams{
	SipURI:            "sip:pbx.example.com:5060",
	Priority:          0,
	DestinationFormat: bird.Ptr("1234#{number}"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(gateway.Id, gateway.Priority)

$gateway = $bird->voice->trunks->gateways->create(
    'TRUNK_ID',
    (new VoiceTrunkGatewayCreate())
        ->setSipUri('sip:pbx.example.com:5060')
        ->setPriority(0)
        ->setDestinationFormat('1234#{number}'),
);
echo $gateway->getId(), ' ', $gateway->getPriority(), "\n";

bird voice trunks gateways create <trunk-id> \
  --destination-format '1234#{number}' \
  --priority 0 \
  --sip-uri sip:pbx.example.com:5060

curl -X POST "https://{region}.platform.bird.com/v1/voice/trunks/{trunk_id}/gateways" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sip_uri": "sip:pbx.example.com:5060",
    "priority": 0,
    "destination_format": "1234#{number}"
  }'

Atualize um gateway para alterar sua prioridade ou formatos depois.

Aviso: desativar chamadas de entrada em um trunk, ou excluir o trunk, faz todos os números apontados para ele voltarem à rota padrão do espaço de trabalho. Uma rota padrão do espaço de trabalho que referencia o trunk volta a rejeitar. Reativar chamadas de entrada não restaura nenhuma das duas configurações, então cada número precisa ser apontado para um trunk novamente.

Definir uma rota padrão

A rota padrão do espaço de trabalho atende chamadas para todos os números sem rota própria. Ela começa como rejeitar. Um número com rota própria a mantém quando o padrão muda.

1. Abra Voice > Numbers.
2. Ao lado de Calls to numbers without their own route, selecione Change, escolha a resposta e salve.

A alteração se aplica a partir da próxima chamada que cada um desses números receber. Pela API, atualize as configurações de voz:

curl -X PATCH "https://{region}.platform.bird.com/v1/voice/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_configuration": {
      "route": {
        "type": "trunk",
        "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  }'

A rota padrão é verificada da mesma forma que a rota de um número. Para devolver um número ao padrão, defina sua rota como null, ou escolha Use the workspace default no número.

Encaminhar chamadas para outro número

Um encaminhamento atende a chamada recebida e faz uma segunda chamada para um número que você verificou, conectando as duas em seguida.

1. Abra Voice > Numbers, abra o número e, em Inbound routing, escolha Forward to another number.
2. Escolha o número para encaminhar. A lista contém os seus caller IDs verificados, porque um encaminhamento só pode ter como destino um número que você provou controlar.
3. Escolha qual número a chamada encaminhada mostra como chamador e selecione Save.

Pela API, pesquise seus números de voz pelos dígitos do número para ler o ID vnu_ dele, e então envie uma rota forward com forward_to e forward_as:

const number = await bird.voice.numbers.update("NUMBER_ID", {
  inbound_configuration: {
    route: { type: "forward", forward_to: "+14155551234", forward_as: "dialed_number" },
  },
});
console.log(number.id, number.inbound_configuration?.route?.type);

var route bird.VoiceCallRouteWritable
if err := route.FromVoiceCallRouteForward(bird.VoiceCallRouteForward{
	ForwardTo: "+14155551234",
	ForwardAs: "dialed_number",
}); err != nil {
	log.Fatal(err)
}
number, err := client.Voice.Numbers.Update(context.Background(), "NUMBER_ID", bird.VoiceNumbersUpdateParams{
	InboundConfiguration: &bird.VoiceInboundConfigurationPut{Route: route},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(number.Id)

$number = $bird->voice->numbers->update(
    'NUMBER_ID',
    (new VoiceNumberUpdate())->setInboundConfiguration(
        (new VoiceInboundConfigurationPut())->setRoute([
            'type' => 'forward',
            'forward_to' => '+14155551234',
            'forward_as' => 'dialed_number',
        ]),
    ),
);
echo $number->getId(), "\n";

bird voice numbers update <number-id> --route forward --forward-to +14155551234 --forward-as dialed_number

curl -X PATCH "https://{region}.platform.bird.com/v1/voice/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_configuration": {
      "route": {
        "type": "forward",
        "forward_to": "+14155551234",
        "forward_as": "dialed_number"
      }
    }
  }'

forward_to precisa ser um caller ID cuja verificação esteja completa. Um número que você não registrou, ou cuja verificação esteja pending ou failed, é recusado com 412 e E21053. Caller IDs cobre como registrar e verificar um pela API.

O destino do encaminhamento é verificado quando você o define e novamente em cada chamada encaminhada. Um caller ID que você remover depois interrompe o encaminhamento em vez de continuar, e as chamadas recebidas passam a ser rejeitadas a partir desse ponto.

A chamada encaminhada toca por 45 segundos antes de ser abandonada, o que é mais do que uma entrega por trunk toca, porque a outra ponta geralmente é o telefone de uma pessoa e não um sistema telefônico.

O encaminhamento faz uma chamada, então as regras de saída se aplicam ao segundo trecho: encaminhar para um país que você não ativou em Destinations é recusado com destination_not_enabled.

Um encaminhamento, dois registros de chamada

Uma chamada encaminhada produz dois registros de trecho que compartilham um call_id:

Use o filtro call_id na lista de trechos para encontrar as conexões relacionadas, ou abra Voice > Calls. O registro de chegada é o que diz o que o número estava configurado para fazer.

Escolher qual número uma chamada encaminhada mostra como chamador

Uma chamada encaminhada tem dois números que pode apresentar a quem atende, e a escolha altera tanto o que a pessoa vê quanto a probabilidade de uma operadora interferir na chamada:

• Número chamador é o próprio número de quem ligou, então o telefone toca como se a pessoa tivesse discado diretamente e a chamada pode ser retornada pelo registro de chamadas. Como o número não é um que você possui, algumas operadoras, mais frequentemente nos EUA e em partes da Europa, marcam essas chamadas como não verificadas, substituem o número ou as filtram.
• Número discado é o número que o chamador discou, que é um dos seus. Quem atende vê qual dos seus números foi chamado em vez de quem ligou.

Declare a escolha em cada encaminhamento que você configurar pela API ou CLI. Uma configuração mais antiga sem escolha armazenada retorna o número discado.

O inbound_configuration.forward_as_options do número lista as opções disponíveis para o editor. As opções atuais incluem o número chamador e o número discado. Leia essas opções ao construir uma integração e use o forward_as retornado para confirmar a configuração efetiva.

Em uma leitura, forward_as é o valor que as chamadas realmente carregam, que pode diferir do último valor gravado.

Consultar o que um número fez com uma chamada

O registro de uma chamada recebida carrega um route junto com o seu status, e route é o que o número estava configurado para fazer no momento em que a chamada foi tratada. Alterar a configuração do número depois não muda o que as chamadas passadas dizem.

route diz o que o número estava configurado para fazer, não que funcionou. Uma rota trunk em uma chamada que nunca conectou é um número apontado para um trunk que não atendeu a chamada, e o status da chamada é o que carrega o resultado. route está ausente em chamadas de saída e em chamadas registradas antes de o campo existir.

No painel, abra a chamada em Voice > Legs e leia a linha Inbound route, que aponta para o número cujas configurações a decidiram. Pela API, route está em GET /v1/voice/legs/{leg_id} e GET /v1/voice/legs, e direction filtra a lista para chamadas recebidas.

Para uma rota de sequência, consulte também a página Runs da sequência para identificar a entrada e a versão executadas. A configuração atual do número pode ser diferente da versão preservada por uma chamada anterior.

Diagnosticar uma chamada recebida recusada

Uma chamada recebida que foi recusada é registrada com o status rejected. Duas coisas diferentes o produzem, e rejection_reason é o que as separa:

• Rejeitada sem rejection_reason. O próprio número recusou a chamada. A chamada não falhou em nenhuma verificação nossa, então não indica motivo, e route diz o que o número estava configurado para fazer. Uma rota reject é um número configurado para recusar, ou um sem rota própria enquanto a rota padrão do espaço de trabalho é rejeitar.
• Rejeitada com um rejection_reason. A chamada falhou em uma de nossas verificações antes de chegar ao seu sistema telefônico. O motivo indica a verificação. Chamadas rejeitadas lista todos os motivos e suas correções.

failed é um status diferente e não significa recusada: significa que a chamada foi tentada e não funcionou, com sip_response_code carregando a resposta que retornou.

Leia route e rejection_reason juntos para distinguir as recusas:

Os limites da conta se aplicam também a chamadas recebidas: além do saldo da sua carteira, do limite diário de gastos com voz da sua organização, ou dos limites de concorrência e por segundo, uma chamada recebida é rejeitada com o motivo correspondente. Visão geral de voz cobre os próprios limites.

Verificar o custo de uma chamada recebida

Receber uma chamada é cobrado. A tarifa depende do país e do tipo do número que recebe, e é publicada por país em Receiving calls na página de preços de voz, junto com as tarifas para chamadas que você faz.

Um encaminhamento é cobrado como duas chamadas: a chamada que chegou pela tarifa de recebimento, e o trecho que fazemos pela tarifa de saída do número para o qual você encaminha. Uma única taxa de manuseio é cobrada uma vez pela chamada, e não uma vez por trecho.

A carteira é verificada antes de uma chamada recebida ser entregue, então um saldo que não pode cobri-la significa que a chamada é rejeitada em vez de ser cobrada de você depois. Custo e faturamento cobre como o tempo faturável, as tarifas e a carteira funcionam para ambas as direções.

Próximos passos