Eventos de voz

Bird emite eventos webhook cuando una llamada comienza, se responde y termina. Úsalos para actualizar tus sistemas sin tener que consultarlos periódicamente. Consulta Webhooks para suscripciones, firmas, reintentos y reproducción.

Recorrido de una llamada a través de los tipos de evento:

1. voice_call.initiated: Bird aceptó la solicitud de establecimiento de llamada (un SIP INVITE) y comenzó a enrutar la llamada
2. voice_call.answered: el número al que llamaste contestó. Solo las llamadas respondidas generan este evento
3. voice_call.ended: la llamada terminó y el evento incluye el resultado

voice_call.initiated confirma que una llamada existe, mientras que voice_call.ended informa su resultado. Para una llamada rechazada o fallida, usa el estado reportado y la respuesta SIP final junto con el registro de llamada. No deduzcas un ciclo de vida completo a partir de la presencia de un solo evento.

El type de evento es un enum abierto: Bird puede agregar tipos con el tiempo, así que maneja los que reconozcas e ignora el resto en lugar de tratar un tipo desconocido como un error.

El sobre del evento

Los eventos de voz llegan en el mismo sobre anidado que cualquier otro evento de Bird, descrito en la guía de Webhooks: type, timestamp y un objeto data específico del tipo. La identidad del evento está en el encabezado webhook-id HTTP en lugar del cuerpo.

El data de cada evento de voz contiene los mismos campos de identidad para correlación. Los números de teléfono usan formato E.164: un + inicial, el código de país y el número nacional. En una llamada desde el navegador a un usuario o grupo de llamada del espacio de trabajo, from puede ser el ID de usr_ de quien llama. Las llamadas desde el navegador a usuarios, grupos de llamada y secuencias del espacio de trabajo están en versión preliminar. Las partes también pueden ser extensiones de SIP, y to puede ser el ID de un usuario del espacio de trabajo, de un grupo de llamada o de una secuencia.

Los nombres de campo del evento difieren de los del tramo API: el call_id del evento identifica el tramo y coincide con el id de la respuesta del tramo; el session_id del evento coincide con el call_id de la respuesta del tramo. Usa esa correspondencia al unir las actualizaciones de webhook con los registros de API.

Estos eventos de ciclo de vida usan el contrato compartido de entrega y firma de webhooks. El paso de webhook síncrono de una secuencia usa un protocolo receptor separado, firmado con el secreto de callback del espacio de trabajo en lugar del secreto de una suscripción a eventos.

voice_call.initiated

Bird recibió el INVITE y comenzó el enrutamiento.

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

El destinatario contestó y el tiempo facturable comenzó. Una llamada no respondida no genera este evento.

La carga útil son los campos de identidad de llamada que incluye cada evento de voz, con timestamp establecido en el momento de la respuesta.

voice_call.ended

La llamada terminó. Este evento agrega el 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
  }
}

Este evento no indica por qué terminó una llamada. Una llamada que alcanzó el límite de duración de llamada de la plataforma llega como un fin answered normal, con un duration_ms de aproximadamente 4 horas.

El registro de llamada contiene dos detalles que este evento omite: el motivo de rechazo y el costo. Abre la llamada en el registro de llamadas para distinguir un rechazo Bird de un fallo del operador. El costo aparece después de que se completa la tarificación.

Consumirlos de forma segura

• Deduplica por webhook-id. Un reintento de señalización o entrega puede repetir una actualización. La publicación repetida de la misma etapa de llamada conserva su identidad de entrega, así que usar esa clave elimina el duplicado.
• No dependas del orden. Las entregas no están ordenadas, así que answered puede llegarte después de ended. Ordena por timestamp y deja que un evento que llega después con una marca de tiempo anterior pierda.
• Usa ended para el resultado reportado. Contiene el estado y las duraciones. La publicación del evento puede fallar antes de que la entrega se encole, así que la ausencia de un evento no significa que la llamada siga activa.
• Reconcilia contra los registros de llamadas. Los eventos proporcionan actualizaciones oportunas, mientras que el registro de llamadas contiene el registro de la llamada. Exporta las llamadas como CSV para la reconciliación.

Próximos pasos