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, verificação de assinatura, tentativas de reenvio e replay.

O caminho de uma chamada pelos tipos de evento:

1. voice_call.initiated: Bird aceitou a solicitação de configuração da chamada (um SIP INVITE) e começou a rotear a chamada
2. voice_call.answered: o número que você chamou atendeu. Apenas chamadas atendidas recebem este evento
3. voice_call.ended: a chamada terminou, e o evento carrega o resultado

voice_call.initiated confirma que uma chamada existe, enquanto voice_call.ended relata seu resultado. Para uma chamada recusada ou com falha, use o status reportado e a resposta SIP final junto com o registro da chamada. Não deduza um ciclo de vida completo a partir da presença de um único evento.

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.

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.

Os nomes dos campos do evento diferem do API da perna: o call_id do evento identifica a perna e corresponde ao id da resposta da perna; o session_id do evento corresponde ao call_id da resposta da perna. Use esse mapeamento ao vincular atualizações de webhook a registros de API.

Esses eventos de ciclo de vida usam o contrato compartilhado de entrega e assinatura de webhooks. O passo síncrono de webhook de uma sequência usa um protocolo receptor separado e não assinado; configurar uma assinatura de evento não autentica solicitações desse passo.

voice_call.initiated

Bird recebeu o INVITE e começou o roteamento.

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

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

• Deduplique pelo webhook-id. Uma retentativa de sinalização ou entrega pode repetir uma atualização. A publicação repetida do mesmo estágio de chamada mantém sua identidade de entrega, então usar essa 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.
• Use ended para o resultado reportado. Ele traz status e durações. A publicação do evento pode falhar antes de a entrega ser enfileirada, então um evento ausente não significa que a chamada ainda está ativa.
• Reconcilie com os registros de chamada. Eventos fornecem atualizações oportunas, enquanto o call log mantém o registro da chamada. Exporte chamadas como CSV para reconciliação.

Próximos passos