Actualizaciones de Llamada

Envía notificaciones HTTP en tiempo real a tu endpoint conforme una llamada avanza por su ciclo de vida. Úsalo para rastrear el estado de la llamada desde tu sistema en el momento exacto en que ocurre cada transición.

Entrega

• Método: POST
• Content-Type: application/json
• Timeout de la petición: 10 segundos. Si tu endpoint no responde en 10s, tratamos el intento como fallido y reintentamos.

Estados

Se emite un único tipo de evento call.updated con un campo status que indica qué transición ocurrió.

status	Se emite cuando
initiated	Se ha confirmado el marcado al número. El registro de la llamada se ha creado y el marcado se ha enviado a la telefonía.
in-progress	La llamada ha sido contestada y la conversación está en curso.

Se pueden añadir más estados en el futuro. Tu handler debe ignorar cualquier status que no reconozca en lugar de rechazar la petición.

Payload

Todas las peticiones comparten la misma estructura JSON. Solo status y timestamp cambian entre eventos.

{
  "event": "call.updated",
  "status": "initiated",
  "timestamp": "2026-04-17T14:32:08.512Z",
  "call": {
    "id": "cHYqKdGz25Rq"
  },
  "agent": {
    "name": "Sofia Sales Agent",
    "slug": "sofia-sales-agent"
  },
  "customer": {
    "name": "Jane Doe",
    "phoneNumber": "+15551234567"
  }
}

Campos Principales

Campo	Tipo	Descripción
event	string	Siempre "call.updated".
status	string	"initiated" o "in-progress".
timestamp	string	Timestamp ISO-8601 UTC del momento en que ocurrió la transición.
call.id	string	Identificador único de la llamada. Consistente en todos los webhooks que refieren a la misma llamada.
agent.name	string	Nombre legible del agente.
agent.slug	string	Slug estable del agente.
customer.name	string	Opcional. Presente cuando se proporcionó un nombre al crear la llamada.
customer.phoneNumber	string	Número telefónico de destino en formato E.164.

Orden de los eventos

Para una llamada típicamente recibirás los eventos en este orden:

1. call.updated con status: "initiated"
2. call.updated con status: "in-progress" (solo si la llamada es contestada)
3. Los eventos existentes de Fin de Llamada / Fin de Sesión

Debido a que los eventos se entregan de forma independiente y los reintentos pueden reordenarlos en escenarios de fallo poco frecuentes, no dependas del orden estricto.

Respuesta a los eventos

Regresa cualquier código HTTP 2xx para confirmar la recepción. No inspeccionamos el cuerpo de la respuesta.

Cualquiera de los siguientes se trata como un fallo y dispara un reintento:

• Una respuesta 3xx, 4xx o 5xx
• Un error de red (conexión rechazada, fallo de DNS, error de TLS)
• Sin respuesta dentro del timeout de 10 segundos

Tu endpoint debe ser idempotente. Dado que reintentamos ante cualquier respuesta no-2xx, el mismo evento puede ser entregado más de una vez. Deduplica usando call.id + status.

Intenta responder en mucho menos de 10 segundos — idealmente confirma de inmediato (por ejemplo, encolando el evento del lado de tu sistema) y realiza cualquier procesamiento pesado de forma asíncrona.

Política de reintentos

Las entregas fallidas se reintentan automáticamente con backoff exponencial:

Intento	Demora tras el intento anterior
1	— (entrega inicial)
2	2 segundos
3	4 segundos
4	8 segundos
5	16 segundos
6	32 segundos

Después de seis intentos el evento se descarta y no se reenviará. Si tu endpoint estuvo caído por más tiempo que la ventana de reintentos, deberías reconciliar el estado usando el webhook de Fin de Llamada o nuestra API en lugar de esperar un reenvío.