Webhook de confirmaciones de lectura

{
  "event": "message_status",
  "whatsapp_message_id": 890,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "meta_message_id": null,
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "sender": {
    "id": 42,
    "phone_number": "+19876543210",
    "display_name": "My Business"
  },
  "to": "+1234567890",
  "from": "+19876543210",
  "direction": "outbound",
  "status": "delivered",
  "error_code": null,
  "error_message": null,
  "error_description": null,
  "timestamp": "2026-06-08T09:30:02+00:00",
  "provider_timestamp": "2026-06-08T09:30:00+00:00"
}

{
  "event": "message_status",
  "whatsapp_message_id": 890,
  "message_sid": null,
  "meta_message_id": "wamid.HBgLMTIzNDU2Nzg5MBUCABEYEjk...",
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "sender": {
    "id": 42,
    "phone_number": "+19876543210",
    "display_name": "My Business"
  },
  "to": "+1234567890",
  "from": "+19876543210",
  "direction": "outbound",
  "status": "read",
  "error_code": null,
  "error_message": null,
  "error_description": null,
  "timestamp": "2026-06-08T09:31:12+00:00",
  "provider_timestamp": "2026-06-08T09:31:10+00:00"
}

{
  "event": "message_status",
  "whatsapp_message_id": 891,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "meta_message_id": null,
  "conversation_id": null,
  "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "sender": {
    "id": 42,
    "phone_number": "+19876543210",
    "display_name": "My Business"
  },
  "to": "+1234567890",
  "from": "+19876543210",
  "direction": "outbound",
  "status": "failed",
  "error_code": 63016,
  "error_message": "Template message 24h window expired",
  "error_description": "Template message 24h window expired - customer must reply first",
  "timestamp": "2026-06-08T09:32:00+00:00",
  "provider_timestamp": null
}

API de Famulor 1.0 (legado). Esta página se aplica únicamente a Famulor 1.0 (app.famulor.de) y se conserva por compatibilidad. Para la plataforma actual, usa la referencia de la API de Famulor 2.0.

Webhook firmado que se envía en cada cambio de estado de entrega (sent, delivered, read, failed) de un mensaje de WhatsApp que envías

El Webhook de confirmaciones de lectura envía un callback HTTP firmado a tu servidor cada vez que cambia el estado de un mensaje de WhatsApp que has enviado — sent, delivered, read o failed. Úsalo para el seguimiento de entregas, la confirmación de lectura y los registros de auditoría. Se configura por remitente de WhatsApp, de modo que distintos remitentes pueden apuntar a endpoints diferentes.

Configuración del webhook

Para activar las confirmaciones de lectura de un remitente:

Edita tu remitente de WhatsApp y abre la sección Webhook de confirmaciones de lectura
Introduce tu URL de webhook y guarda
Se genera automáticamente un secreto de firma — úsalo para verificar la firma de cada solicitud

Cada payload incluye el whatsapp_message_id devuelto por los endpoints Enviar mensaje de plantilla y Enviar mensaje de texto libre, de modo que puedas asociar cada actualización con el mensaje original.

Formato de la solicitud

El webhook se envía como una solicitud POST a tu URL configurada con un cuerpo JSON y un encabezado X-Signature-256.

Estructura del payload

string

El tipo de evento. Valor: message_status

integer

Identificador numérico del mensaje — el mismo whatsapp_message_id devuelto al enviar el mensaje. Úsalo para correlacionar la actualización de estado con el envío original.

string

Identificador del mensaje del proveedor para mensajes enviados a través de Twilio, o null

string

Identificador del mensaje del proveedor (wamid de WhatsApp) para mensajes enviados a través de la Meta Cloud API, o null

string

Identificador único (UUID) de la conversación a la que pertenece el mensaje, o null

string

Identificador único (UUID) del asistente conectado al remitente, o null

object

El remitente de WhatsApp desde el que se envió el mensaje

Mostrar Propiedades del remitente

integer

Identificador numérico del remitente

string

El número de teléfono de WhatsApp del remitente

string

El nombre visible del remitente

string

El número de teléfono del destinatario

string

El número de teléfono del remitente

string

Dirección del mensaje. Valor: outbound

string

El nuevo estado de entrega. Valores posibles: sent, delivered, read, failed, undelivered

integer

Código de error del proveedor cuando status es failed o undelivered; en caso contrario, null

string

Mensaje de error sin procesar del proveedor cuando el mensaje falló; en caso contrario, null

string

Descripción legible para humanos del error; en caso contrario, null

string

Marca de tiempo ISO 8601 de cuándo la plataforma registró el cambio de estado, en la zona horaria configurada del propietario del número de WhatsApp

string

Marca de tiempo ISO 8601 de la hora del evento según el propio operador, en la zona horaria configurada del propietario. Presente en los mensajes enviados a través de la Meta Cloud API; null en Twilio (el callback de estado de Twilio no incluye una hora de evento). Prefiere este valor cuando esté presente — es la hora autorizada por el operador.

{
  "event": "message_status",
  "whatsapp_message_id": 890,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "meta_message_id": null,
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "sender": {
    "id": 42,
    "phone_number": "+19876543210",
    "display_name": "My Business"
  },
  "to": "+1234567890",
  "from": "+19876543210",
  "direction": "outbound",
  "status": "delivered",
  "error_code": null,
  "error_message": null,
  "error_description": null,
  "timestamp": "2026-06-08T09:30:02+00:00",
  "provider_timestamp": "2026-06-08T09:30:00+00:00"
}

{
  "event": "message_status",
  "whatsapp_message_id": 890,
  "message_sid": null,
  "meta_message_id": "wamid.HBgLMTIzNDU2Nzg5MBUCABEYEjk...",
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "sender": {
    "id": 42,
    "phone_number": "+19876543210",
    "display_name": "My Business"
  },
  "to": "+1234567890",
  "from": "+19876543210",
  "direction": "outbound",
  "status": "read",
  "error_code": null,
  "error_message": null,
  "error_description": null,
  "timestamp": "2026-06-08T09:31:12+00:00",
  "provider_timestamp": "2026-06-08T09:31:10+00:00"
}

{
  "event": "message_status",
  "whatsapp_message_id": 891,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "meta_message_id": null,
  "conversation_id": null,
  "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "sender": {
    "id": 42,
    "phone_number": "+19876543210",
    "display_name": "My Business"
  },
  "to": "+1234567890",
  "from": "+19876543210",
  "direction": "outbound",
  "status": "failed",
  "error_code": 63016,
  "error_message": "Template message 24h window expired",
  "error_description": "Template message 24h window expired - customer must reply first",
  "timestamp": "2026-06-08T09:32:00+00:00",
  "provider_timestamp": null
}

Verificación de la firma

Cada solicitud incluye un encabezado X-Signature-256 que contiene un HMAC-SHA256 del cuerpo de la solicitud sin procesar, firmado con el secreto de firma de tu remitente:

X-Signature-256: sha256=<hmac_sha256(raw_body, signing_secret)>

Vuelve a calcular la firma sobre el cuerpo sin procesar y compárala usando una comparación de tiempo constante. Rechaza la solicitud si no coincide.

import crypto from "crypto";

function isValid(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader || "")
  );
}

function isValid(string $rawBody, ?string $signatureHeader, string $secret): bool
{
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

    return hash_equals($expected, (string) $signatureHeader);
}

Comportamiento de los reintentos

Si tu endpoint devuelve un estado que no es 2xx o la solicitud falla, la entrega se reintenta:

Intento	Retraso
1.er reintento	30 segundos
2.º reintento	60 segundos
3.er reintento	120 segundos

Los errores del servidor (5xx) y los límites de frecuencia (429) se reintentan. Los errores del cliente (4xx) se consideran un endpoint mal configurado y no se reintentan.

Notas importantes

El webhook se configura por remitente — cada remitente puede tener su propia URL y su propio secreto.
Los eventos activados por el botón Realizar solicitud de prueba en los ajustes del remitente incluyen un campo adicional test: true y usan valores de ejemplo. Las actualizaciones de estado reales nunca incluyen test.
read solo se dispara si el destinatario tiene activadas las confirmaciones de lectura en su configuración de privacidad de WhatsApp. delivered siempre se dispara.
Los estados pueden llegar fuera de orden o ser reenviados por el proveedor. Solo reenviamos un avance genuino, así que no recibirás un delivered después de un read para el mismo mensaje — pero aun así deberías tratar el webhook como la fuente de verdad y deduplicar por whatsapp_message_id + status.
timestamp es siempre la hora en que la plataforma registró el cambio (en la zona horaria del propietario del número). provider_timestamp es la hora de evento autorizada por el operador cuando está disponible — prefiérela por su precisión, y recurre a timestamp cuando sea null.
Usa Regenerar en los ajustes del remitente para rotar el secreto de firma si alguna vez queda expuesto.

Referencia de la API

Asistentes de IA

Carpetas

Etiquetas

Leads

Campañas

Automatizaciones

Acciones durante la llamada

Chatbot de IA

Respuestas de IA

Bases de conocimiento

SMS

WhatsApp

Números de teléfono

Trunks SIP

Llamadas

Webhooks

Webhook de confirmaciones de lectura

Configuración del webhook

Formato de la solicitud

Estructura del payload

Verificación de la firma

Comportamiento de los reintentos

Notas importantes

​Configuración del webhook

​Formato de la solicitud

​Estructura del payload

​Verificación de la firma

​Comportamiento de los reintentos

​Notas importantes

Configuración del webhook

Formato de la solicitud

Estructura del payload

Verificación de la firma

Comportamiento de los reintentos

Notas importantes