FAQ da Voice API

O Bird Voice permite fazer chamadas para números de telefone através de um tronco SIP. Seu sistema telefônico se conecta ao Bird, e o Bird encaminha cada chamada por meio de uma operadora para a rede telefônica pública (a PSTN). Você traz seu próprio PBX ou softphone; o Bird cuida do trecho da operadora.

Cerca de dez minutos. Crie um tronco SIP, verifique um identificador de chamadas, habilite o país de destino e aponte seu sistema telefônico para o endereço do tronco. O guia de primeira chamada percorre todo o processo.

Três coisas do seu lado: um tronco SIP com seu equipamento autorizado (por faixa de IP ou chave de API), um identificador de chamadas verificado (o número que você apresenta como chamador) e o país de destino habilitado. O Bird vincula o roteamento ao seu workspace, que é o quarto pré-requisito e acontece do lado do Bird.

Não. Qualquer sistema telefônico compatível com SIP funciona: um softphone como Zoiper ou Linphone em um laptop, um PBX como Asterisk ou FreeSWITCH, ou um sistema comercial como 3CX ou FreePBX. O Bird fornece um domínio SIP e você aponta seu equipamento para ele.

Sim. Pode efetuar chamadas a partir da aplicação Telefone no painel usando WebRTC.

Por chamada, a uma tarifa que depende do país de destino. Cada tarifa tem um incremento de faturamento: um tempo mínimo cobrado e, depois, o intervalo ao qual é arredondado. Uma tarifa com mínimo de um minuto e intervalos de seis segundos cobra uma chamada de 10 segundos como um minuto inteiro.

O tempo faturável começa no momento em que o número chamado atende até o momento em que a chamada termina. O tempo de toque não é cobrado, então uma chamada que ninguém atende não custa nada.

Pré-pago, a partir da carteira da sua organização. O Bird verifica seu saldo antes de discar para a operadora, então uma chamada que sua carteira não pode cobrir é recusada antecipadamente com insufficient_balance em vez de cobrada depois.

Sim. Um teto diário de gastos com voz aplica-se por organização, sendo reiniciado no início de cada dia UTC. Acima dele, as chamadas são recusadas com daily_spend_exceeded. O valor depende do seu plano, e a Bird pode aumentá-lo mediante solicitação.

Abra a chamada no registo de chamadas. O custo aparece no registo assim que for tarifado, com precisão total, líquido de impostos. Para totais de várias chamadas, exporte a lista filtrada como CSV a partir da página de Chamadas, ou consulte as suas faturas e utilização.

Três tetos: quantas chamadas você pode ter em andamento ao mesmo tempo (chamadas simultâneas), quantas novas chamadas pode iniciar por segundo (chamadas por segundo) e quanto pode gastar em voz em um dia UTC (gasto diário). Cada um é definido por organização, e os valores dependem do seu plano.

A chamada é recusada na configuração, antes de qualquer operadora ser discada. O registro da chamada identifica qual limite foi atingido: concurrent_calls_exceeded, calls_per_second_exceeded ou daily_spend_exceeded. Seu sistema telefônico recebe um SIP 503.

Sim. Entre em contato com o suporte para solicitar um teto maior de chamadas simultâneas ou chamadas por segundo. O teto de gasto diário depende do seu plano e também pode ser aumentado.

Verifique qual motivo o registro da chamada indica. Um discador pode atingir calls_per_second_exceeded mesmo longe do teto de chamadas simultâneas, porque os dois limites são independentes. Reduza a taxa de discagem e tente novamente; tentar novamente imediatamente resulta na mesma resposta.

Um SIP trunk é a conexão entre o seu sistema telefónico e a Bird. SIP (Session Initiation Protocol) é a linguagem que os sistemas telefónicos usam para estabelecer chamadas, e um trunk é a linha por onde essas chamadas passam. A Bird atribui ao seu workspace um endereço de trunk, e você aponta o seu sistema telefónico para ele.

A maioria dos workspaces precisa de apenas um. Crie mais quando quiser regras de acesso separadas por local ou por sistema, uma vez que a lista de IPs permitidos, as chaves API autorizadas e as configurações de Digest são todas por trunk.

O domínio SIP do trunk (copiado da página do trunk), o nome de utilizador bird e a palavra-passe (o segredo de uma chave API autorizada no trunk). Envie chamadas para o domínio SIP na porta 5060 (UDP ou TCP) ou 5061 (TLS).

Sim, com uma lista de IPs permitidos, chaves API autorizadas, ou ambos. Adicione os endereços públicos de onde o seu equipamento envia SIP, ou exija que cada chamada se autentique com uma chave API via SIP Digest. Ambos entram em vigor na próxima chamada.

O domínio SIP do trunk deixa de aceitar novas chamadas imediatamente. As chamadas já em curso continuam, e os registos de chamadas feitos através do trunk permanecem no seu registo de chamadas.

O seu PBX envia a chamada, o Bird responde com um desafio 407, e o seu PBX reenvia a chamada com um cabeçalho Proxy-Authorization calculado a partir do nome de utilizador bird e o segredo da sua API key como palavra-passe. O seu PBX envia um hash da palavra-passe, nunca a palavra-passe em si.

SHA-256 e MD5. O Bird oferece SHA-256 primeiro e MD5 em segundo por padrão, e o seu PBX escolhe o primeiro que suporta. Se o seu equipamento apenas suporta MD5 e não lida corretamente com um desafio que começa com SHA-256, defina o trunk apenas para MD5.

Sim. Quando um trunk tem ambos, o endereço de origem é verificado antes de o Bird solicitar uma palavra-passe, pelo que uma chamada de um endereço não listado é recusada independentemente das credenciais que transporta.

Adicione a nova chave ao trunk primeiro, migre o seu equipamento e depois revogue a antiga. Revogar ou eliminar uma chave remove imediatamente a sua capacidade de autenticação em todos os trunks que a permitiam.

Um caller ID é um número de telefone que o seu workspace está autorizado a apresentar como chamador em chamadas de saída. O Bird verifica o número de chamada que o seu equipamento coloca no cabeçalho SIP From contra esta lista em cada chamada, para que as chamadas saiam apenas com números que verificou.

Adicione o número na página de Números no formato E.164. Bird efetua imediatamente uma chamada de verificação para o número. Atenda a chamada, ouça o código de seis dígitos e introduza-o no painel. Tem cinco tentativas e o número fica utilizável assim que uma for aceite.

Se as tentativas se esgotaram, utilize Obter um novo código na linha do número para uma nova chamada de verificação. Se o número ainda estiver à espera do código, remova o identificador de chamadas e adicione o número novamente.

Redirecione-o para um telefone que possa atender durante o minuto que a verificação demora e depois reverta. Para um número que não recebe chamadas de todo, contacte o suporte.

A partir desse momento, qualquer chamada que apresente esse número é recusada com caller_id_not_verified. As chamadas já em curso continuam, e os registos de chamadas que usaram o número permanecem inalterados.

A fraude de portagem funciona ao marcar países caros que nunca pretendeu ligar. Os países que ativa são aqueles nos quais pode acumular custos, pelo que deixar tudo o resto desativado limita a sua exposição caso alguém invada o seu sistema telefónico.

Encontre o país na página de Destinos usando a caixa de pesquisa (pesquisa por nome ou código de duas letras) e ative o respetivo botão. A alteração aplica-se a partir desse momento.

As chamadas para países de alto risco são caras, e quem opera o número que marca recebe uma parte do custo. Estes são os países que um atacante visa se invadir um sistema telefónico. Deixe-os desativados a menos que tenha negócios lá, e verifique a tarifa antes de ativar um.

Contacte o suporte para que seja aberto para a sua conta. Available significa que pode ativá-lo; Not supported significa que o Bird não consegue atualmente efetuar chamadas para esse país a partir da sua conta.

Um país disponível pode ainda ter destinos específicos dentro dele que o encaminhamento ainda não alcança. Envie o ID da chamada ao suporte e eles irão estender o encaminhamento para o cobrir.

Dois cabeçalhos: To (o número sendo chamado) e From (o número que você apresenta como chamador, que deve ser um identificador de chamadas verificado). Ambos devem ser números internacionais completos no formato E.164, um + inicial seguido do código do país e do número nacional. Nenhum cabeçalho personalizado é necessário.

STIR/SHAKEN é uma assinatura que as operadoras usam ao decidir se deixam uma chamada passar sem rótulo. Chamadas para os Estados Unidos e a França incluem automaticamente, sem nada para configurar. As chamadas carregam nível B por padrão; o nível A (o mais forte) está disponível mediante solicitação.

Abra a chamada no registro de chamadas. Seu sistema telefônico vê apenas um SIP 503 genérico, mas o motivo específico fica no registro da chamada, onde só você pode lê-lo. Um painel acima dos detalhes indica a causa e leva à configuração que a corrige.

Somente quando a causa for eliminada. Uma chamada recusada por calls_per_second_exceeded receberá a mesma resposta até você reduzir a taxa de discagem. Leia o motivo da rejeição antes de tentar novamente.

Cinco: Answered (o número chamado atendeu), No answer (tocou até expirar), Failed (a chamada não foi completada, seja porque o Bird a recusou ou uma operadora falhou), Rejected (a operadora recusou a chamada de imediato) e Unknown (o resultado não pôde ser determinado).

Ambas aparecem como Failed. O motivo da rejeição é o que as separa: apenas uma recusa do Bird inclui um. Uma chamada falhada com motivo de rejeição aponta para uma configuração do seu lado ou do Bird; uma sem motivo de rejeição geralmente aponta para o número que marcou.

Sim. O separador Live na página de Chamadas lista as chamadas nos seus trunks neste momento, com uma contagem. Uma chamada em direto aparece como Ringing (à espera que o outro lado atenda) ou In progress (conectada). O separador atualiza a cada poucos segundos.

A duração total conta desde o momento em que o Bird recebeu a chamada até ao desligar. O tempo faturável conta desde o atendimento até ao desligar. A diferença é o tempo de toque sem que ninguém atendesse, pelo que uma diferença grande merece uma análise ao que está a marcar. Uma chamada não atendida não tem custo.

Três formas: descarregar CSV da página de Chamadas (exporta todos os registos que correspondem aos seus filtros atuais, não apenas a página visível), lê-los através da API com uma API key com permissão voice:read, ou usar o Bird CLI com bird voice list.

Três: voice_call.initiated (o Bird aceitou a chamada e iniciou o encaminhamento), voice_call.answered (o número chamado atendeu) e voice_call.ended (a chamada terminou, com o resultado). Uma chamada não atendida nunca emite o evento answered.

Uma chamada que o Bird recusa após aceitar o INVITE ainda termina com voice_call.ended, com status failed e sip_response_code 503. Assim, toda chamada que você recebe como aberta também é fechada. Uma chamada que o Bird não consegue admitir de forma alguma (rejeitada na camada SIP) nunca produz nenhum evento.

Sim. As entregas não são ordenadas, então answered pode chegar após ended. Ordene pelo campo timestamp e deixe um evento que chegou depois, mas com timestamp anterior, perder.

Faça a deduplicação pelo cabeçalho HTTP webhook-id. O Bird entrega pelo menos uma vez, e o evento initiated de uma chamada pode ser publicado mais de uma vez quando uma retentativa de sinalização o repete. Mesma chamada, mesmo estágio, mesmo webhook-id.

Eles ficam no registro da chamada, não no evento. Um status failed em voice_call.ended não indica se foi o Bird ou uma operadora que causou. Abra a chamada no registro de chamadas para ver o motivo de rejeição; o custo aparece lá assim que a chamada for tarifada.

Uma chamada que a Bird não consegue admitir é rejeitada na camada SIP, antes de existir um registo. Verifique quatro coisas: o trunk tem um intervalo de IP ou chave API que autoriza o seu equipamento, a chamada chegou de um endereço na lista de IPs permitidos do trunk (atrás de NAT, esse é o endereço público do router), as credenciais Digest estão corretas (nome de utilizador bird, o segredo da chave API correto, um algoritmo que o trunk oferece) e o domínio SIP corresponde exatamente ao domínio do trunk.

Abra a chamada no registo de chamadas. O painel acima dos detalhes indica a causa e aponta para a configuração que a resolve. Os sete motivos que pode corrigir são source_not_allowed, caller_id_not_verified, destination_not_enabled, insufficient_balance, daily_spend_exceeded, concurrent_calls_exceeded e calls_per_second_exceeded.

Alguns equipamentos não lidam bem com um desafio que começa com SHA-256. Defina o algoritmo Digest do trunk apenas como MD5, e o seu PBX receberá um desafio que compreende.

O seu cliente está atrás de NAT (um router ou firewall que reescreve endereços) e o áudio está a ser enviado para um endereço privado que o lado remoto não consegue alcançar. Ative o tratamento de NAT ou STUN do seu cliente para que anuncie o seu endereço público na oferta de mídia.

Pode ser. Bird suporta TLS na porta 5061 para sinalização SIP, pelo que a configuração da chamada é encriptada em trânsito. UDP e TCP na porta 5060 não são encriptados. Escolha o transporte que os seus requisitos de segurança exigem.

Cada evento é assinado com HMAC. Verifique a assinatura com o segredo do seu endpoint antes de agir sobre o payload, e faça a rotação desse segredo a partir do painel sempre que necessário.

Na região onde a sua organização está alojada, seja us1 ou eu1. A sua chave API contém essa informação no prefixo (bk_us1_, bk_eu1_), que é como os SDKs e o CLI selecionam o endpoint correto sem necessidade de configuração.

Apenas aquilo a que lhe der permissão. Uma chave contém uma lista de escopos, cada um com leitura ou escrita. Uma chave com voice:write pode autenticar chamadas num trunk; uma chave com voice:read pode listar registos de chamadas. Uma chave não consegue aceder a canais ou configurações fora dos seus escopos.

O motivo específico fica no registo da chamada, onde apenas você pode lê-lo. Retornar um 503 genérico na camada SIP impede que alguém que esteja a sondar o seu trunk descubra quais trunks, números e destinos existem.

As certificações e a documentação de segurança estão no Trust Center em trust.bird.com. O acordo de processamento de dados, a declaração de privacidade e a política de utilização aceitável estão publicados em bird.com/legal. Para um questionário de fornecedor, a equipa da sua conta Bird trata disso.