Eventos de voz
Bird emite eventos de webhook quando uma chamada começa, é atendida e termina. Use-os para atualizar seus sistemas sem polling. Consulte Webhooks para assinaturas, assinaturas de verificação, tentativas de reenvio e replay.
O caminho de uma chamada pelos tipos de evento:
- voice_call.initiated: Bird aceitou a solicitação de configuração da chamada (um SIP INVITE) e começou a rotear a chamada
- voice_call.answered: o número que você chamou atendeu. Apenas chamadas atendidas recebem este evento
- voice_call.ended: a chamada terminou, e o evento carrega o resultado
voice_call.initiated confirma que uma chamada existe, enquanto voice_call.ended reporta seu resultado. Uma chamada que Bird recusa após aceitar o INVITE ainda emite voice_call.ended com status: "failed" e sip_response_code: 503.
O type do evento é um enum aberto: Bird pode adicionar tipos ao longo do tempo, então trate apenas os que você usa e ignore o restante em vez de tratar um tipo desconhecido como erro.
O envelope do evento
Eventos de voz chegam no mesmo envelope aninhado de qualquer outro evento Bird, descrito no guia de Webhooks: type, timestamp e um objeto data específico do tipo. A identidade do evento está no header webhook-id HTTP, não no corpo.
| Campo | Descrição |
|---|---|
| type | Um dos três tipos desta página, por exemplo voice_call.ended |
| timestamp | Quando o evento ocorreu (RFC 3339). Ordene por este campo, nunca pela ordem de chegada |
| data | Payload específico do evento, sempre contendo os mesmos campos de identidade da chamada |
O data de todo evento de voz contém os mesmos campos de identidade para correlação. Ambos os números usam o formato E.164: um + inicial, código do país e número nacional.
| Campo | Descrição |
|---|---|
| call_id | O id do registro da chamada (vcl_…), o mesmo exibido no Call log |
| session_id | Compartilhado por cada perna de uma chamada transferida ou com múltiplos participantes (vcs_…). Null quando não há correlação de sessão aplicável |
| workspace_id | O espaço de trabalho ao qual a chamada pertence |
| direction | outbound para chamadas originadas pelo seu equipamento |
| from | O número de origem |
| to | O número chamado |
voice_call.initiated
Bird recebeu o INVITE e começou o roteamento.
Exemplo de código
{
"type": "voice_call.initiated",
"timestamp": "2026-06-10T14:30:00Z",
"data": {
"call_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
"session_id": "vcs_01krdgeqcxet5s7t44vh8rt9mh",
"workspace_id": "wsp_01krdgeqcxet5s7t44vh8rt9mj",
"direction": "outbound",
"from": "+14155551234",
"to": "+16505559876"
}
}voice_call.answered
O destinatário atendeu e o tempo faturável começou. Uma chamada não atendida não emite este evento.
O payload são os campos de identidade da chamada que todo evento de voz carrega, com timestamp definido como o momento do atendimento.
voice_call.ended
A chamada terminou. Este evento adiciona o resultado:
| Campo | Descrição |
|---|---|
| status | Como terminou: answered, no_answer, failed, rejected ou unknown (veja Statuses) |
| sip_response_code | O código SIP final da chamada, por exemplo 200 ou 486. Uma chamada Bird recusada carrega 503; null quando nenhum código final foi registrado |
| duration_ms | Duração total da chamada em milissegundos, do momento em que Bird recebeu a chamada até o desligamento |
| billable_ms | Tempo atendido em milissegundos; uma chamada que ninguém atendeu reporta zero |
Exemplo de código
{
"type": "voice_call.ended",
"timestamp": "2026-06-10T14:31:05Z",
"data": {
"call_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
"session_id": "vcs_01krdgeqcxet5s7t44vh8rt9mh",
"workspace_id": "wsp_01krdgeqcxet5s7t44vh8rt9mj",
"direction": "outbound",
"from": "+14155551234",
"to": "+16505559876",
"status": "answered",
"sip_response_code": 200,
"duration_ms": 65000,
"billable_ms": 60000
}
}O registro da chamada contém dois detalhes que este evento omite: o motivo da rejeição e o custo. Abra a chamada no call log para distinguir uma recusa Bird de uma falha da operadora. O custo aparece após a conclusão da tarifação.
Consumindo com segurança
- Deduplicação por webhook-id. Bird entrega pelo menos uma vez, e o evento initiated de uma chamada pode ser publicado mais de uma vez quando uma tentativa de sinalização é reenviada. Mesma chamada, mesmo estágio, mesmo webhook-id: usar esse valor como chave elimina a duplicata.
- Não dependa da ordem. As entregas não são ordenadas, então answered pode chegar depois de ended. Ordene por timestamp e descarte um evento que chega depois mas tem um timestamp anterior.
- Trate ended como o único resultado confiável. É o evento que carrega status e durações, e é nele que seus próprios registros devem se basear.
- Reconcilie com os registros de chamada. Eventos fornecem atualizações em tempo real, enquanto o call log mantém o registro da chamada. Exporte chamadas como CSV para reconciliação.
Próximos passos
| Página | O que cobre |
|---|---|
| Webhooks e eventos | Configuração de endpoint, verificação de assinatura, tentativas de reenvio e replay |
| Call log | Todos os campos de um registro de chamada e exportação CSV |
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Entenda o conceitoWhat is a voice API?Explore a funcionalidadeVoiceGuia de implementaçãoVoice overview
Obtenha um resumo de implementação