Como fazer chamadas

Seu PBX envia um INVITE SIP ao domínio SIP do tronco para fazer uma chamada. A Bird verifica a solicitação, encaminha a chamada para uma operadora e retransmite o áudio. Esta página aborda os pré-requisitos, os campos da solicitação, a autenticação e o custo.

Para iniciar uma chamada pelo seu aplicativo via HTTP, use o guia de criação de chamadas. Esse caminho executa uma sequência publicada da Bird após o atendimento.

Antes de fazer uma chamada

O guia Como configurar um tronco SIP apresenta toda a configuração de um tronco, em ordem, para ambas as direções.

Quatro requisitos precisam estar atendidos, em qualquer ordem, e três deles dependem da sua configuração:

• Um tronco que aceite seu tráfego. Crie um tronco SIP e habilite chamadas de saída. Adicione os intervalos de IP do seu equipamento, uma chave de API permitida ou ambos. Clientes que não podem armazenar um segredo de longa duração podem usar uma credencial de sessão.
• Uma identificação de chamada elegível. Use um número da Bird alocado a este espaço de trabalho ou registre um número externo e conclua a chamada de verificação. A verificação não garante a entrega de ponta a ponta da CLI nem a conexão da chamada quando a CLI não é um número adquirido por meio da Bird: consulte a isenção de responsabilidade sobre verificação e entrega da CLI.
• O país de destino habilitado. Habilite os países que você atende na página Destinations.
• Roteamento associado ao seu espaço de trabalho. A Bird configura isso para você, escolhendo quais operadoras atendem a cada destino. Até que essa configuração esteja pronta, as chamadas são recusadas com routing_not_configured, um dos motivos abordados em Chamadas rejeitadas.

O que a Bird espera no INVITE

Envie a solicitação ao domínio SIP do seu tronco em uma das portas compatíveis. A Bird lê três partes da solicitação:

Escreva os números no formato internacional E.164, com + no início, seguido do código do país e do número nacional. A Bird também aceita o mesmo número com 00 no lugar de +, ou apenas com dígitos, começando pelo código do país. A Bird interpreta dígitos sem + ou 00 como se começassem com um código de país. Por isso, um número no formato nacional não é interpretado como o número pretendido. Não adicione um prefixo técnico ao número chamado.

Fora esses requisitos, esta é uma chamada SIP comum, e você não precisa enviar nenhum cabeçalho personalizado.

Ofereça G.711, A-law ou µ-law, no seu SDP. Envie os tons do teclado (DTMF) como eventos telefônicos RFC 4733. O Bird remove outros codecs, como G.729 ou Opus, da oferta que envia à operadora, então inclua G.711 em todas as ofertas.

A mídia usa RTP sem criptografia. SRTP não é compatível. O TLS na porta 5061 criptografa a sinalização, e o áudio permanece sem criptografia.

Autenticação de cada chamada

As etapas pelas quais uma chamada passa dependem de como o acesso ao tronco é configurado:

• Somente lista de IPs permitidos. Uma única solicitação. O Bird confere se o endereço de origem está na lista e encaminha a chamada, sem exigir resposta a um desafio.
• Somente chaves de API permitidas. O Bird primeiro solicita uma senha para a chamada, por meio da troca de mensagens Digest do SIP.
• Ambos. Chamadas que usam uma chave de API permitida também devem vir de um endereço listado. As credenciais de sessão habilitadas oferecem o caminho de admissão separado descrito abaixo.
• Credenciais de sessão habilitadas. O Bird envia um desafio à chamada independentemente da origem, mesmo que o endereço não esteja na lista de permissões. Uma credencial emitida por ele minutos antes responde ao desafio. Equipamentos já autorizados pela lista de permissões em um tronco sem chaves permitidas continuam se conectando sem desafio.

Quando o tronco tem chaves de API permitidas, seu sistema telefônico responde com um hash do segredo da chave de API, em vez do próprio segredo. É assim que funciona a autenticação Digest do SIP:

1. Seu PBX envia o INVITE.
2. O Bird responde com 407 Proxy Authentication Required e uma linha de desafio para cada algoritmo oferecido pelo tronco: por padrão, SHA-256 e depois MD5.
3. Seu PBX reenvia o INVITE com um cabeçalho Proxy-Authorization calculado usando o nome de usuário bird e o segredo da chave de API como senha.
4. A Bird verifica a resposta e continua o roteamento.

Um cabeçalho Proxy-Authorization preventivo é enviado antes do desafio, então seu equipamento deve escolher um algoritmo que o tronco ofereça. Na autenticação por chave de API, um tronco com uma lista de IPs permitidos ainda exige que a solicitação venha de um endereço da lista.

A Bird responde a uma falha na negociação na camada SIP, de modo que a tentativa é recusada antes que a plataforma crie um registro da chamada. Se suas chamadas não aparecerem no registro de chamadas, verifique as credenciais em vez do roteamento.

Atestação de chamadas

Chamadas para os Estados Unidos e a França incluem atestação STIR/SHAKEN. As operadoras usam essa assinatura ao classificar as chamadas. A Bird aplica o nível B por padrão, sem configuração adicional. Entre em contato com o suporte para solicitar o nível A.

Quando uma chamada é recusada

A Bird verifica o identificador de chamadas, o destino, os limites e o saldo da carteira antes de discar para uma operadora. A recusa chega ao seu sistema de telefonia como SIP 503; a causa específica fica no registro da chamada, acessível após autenticação. Abra a chamada no registro de chamadas ou consulte chamadas rejeitadas para ver cada motivo e sua solução.

Resolva a causa registrada antes de tentar novamente. Por exemplo, calls_per_second_exceeded continua ocorrendo até você reduzir a taxa de discagem.

As respostas a uma chamada registrada pela Bird, incluindo o 503 de uma recusa com motivo registrado, contêm um cabeçalho X-BIRD-CALL-ID com o Leg ID da chamada (vcl_…). Consulte o registro com GET /v1/voice/legs/{leg_id} ou informe esse identificador ao suporte.

Chamadas de emergência não são encaminhadas

O Bird Voice não encaminha chamadas para serviços de emergência. Uma chamada para 112, 911, 999 ou qualquer outro número de emergência é recusada em todos os troncos, em todos os países. Seu sistema de telefonia deve acessar os serviços de emergência por outra rota.

Esse comportamento não depende do seu plano, saldo ou destinos. Configure seu sistema de telefonia para rotear chamadas de emergência por um serviço compatível, como uma linha PSTN local, um gateway nas suas instalações ou outro provedor. Teste essa rota. A Bird retorna 503 para uma chamada de emergência recusada, permitindo que um sistema de telefonia tente outra rota do plano de discagem.

Os serviços de emergência dependem da localização cadastrada de quem liga, que a Bird não armazena para um tronco. Não dependa de uma rota da Bird para chamadas de emergência.

Custo e faturamento

O uso de voz é pré-pago e descontado da carteira da sua organização, assim como nos outros canais:

• O tempo faturável vai do atendimento ao encerramento, independentemente de quanto tempo a chamada tocou antes. O registro da chamada mostra esse tempo ao lado de Total duration, que começa no momento em que a Bird recebeu a chamada.
• A tarifa depende do país de destino. Sua tabela de tarifas define o preço para cada país na moeda da carteira. Uma tarifa define um tempo mínimo faturado e o incremento usado após esse mínimo. Por exemplo, uma tarifa com mínimo de um minuto e incrementos de seis segundos cobra uma chamada de 10 segundos como um minuto.
• O saldo da carteira é verificado antes de a chamada ser encaminhada à operadora. Uma chamada que seu saldo não pode cobrir é recusada de imediato com insufficient_balance, em vez de ser cobrada depois. Mantenha uma reserva de saldo ou ative as recargas automáticas.
• Há um limite diário de gastos com voz. Ao ultrapassá-lo, as chamadas são recusadas com daily_spend_exceeded até o início do próximo dia em UTC. Um espaço de trabalho também pode definir um limite diário para cada país de destino em Voice > Destinations, e a chamada deve respeitar ambos os limites. O valor depende do seu plano.
• O custo aparece na chamada depois que ela é tarifada, com precisão total e sem impostos.

Para consultar as cobranças de várias chamadas, use Uso, gastos e faturas. A exportação CSV de Legs inclui as durações e o tempo faturável, mas não tem uma coluna de custo.

Próximos passos