Estructura de los payloads

Envelope del evento

Toda petición enviada a tu webhook tiene la siguiente estructura de nivel superior:

{
  "message": { ... },
  "messageEventType": "NEW_MESSAGE"
}

Campo	Tipo	Descripción
`message`	object	Objeto completo del mensaje
`messageEventType`	string	Tipo de evento: actualmente `"NEW_MESSAGE"` para todos los eventos de mensaje

Campos comunes del mensaje

Todos los payloads comparten los mismos campos dentro del objeto message, con independencia del tipo de contenido:

Campo	Tipo	Descripción
`_id`	string	ID único del mensaje
`tenant`	string	ID del workspace
`tenant_owner`	string	Correo electrónico del propietario del workspace
`channel_id`	string	ID del canal que recibió o envió el mensaje
`created_by`	string	Origen interno del mensaje
`created`	number	Timestamp de creación (epoch en ms)
`metadata.from_api`	boolean	`true` cuando se envió mediante la API
`metadata.from_me`	boolean	`true` cuando lo envió el negocio; `false` cuando se recibió del contacto
`metadata.middleware`	string	Plataforma del canal (p. ej.: `"META_WHATSAPP"`)
`metadata.forwarded`	boolean	`true` si el mensaje fue reenviado
`sender.identifier`	string	Identificador de quien lo envió
`sender.name`	string	Nombre de quien lo envió
`recipient.identifier`	string	Teléfono del destinatario (código de país + prefijo + número)
`contents`	array	Contenidos textuales e interactivos del mensaje
`attachments`	array	Adjuntos multimedia (imagen, audio, vídeo, sticker)
`webhook_processed`	boolean	Control interno de procesamiento

Mensajes de grupo (WhatsApp Web)

En los canales WhatsApp Web (metadata.middleware igual a "Z_API_WHATSAPP"), un mensaje intercambiado en un grupo trae la identificación del grupo en el internal_information de cada elemento de contents y attachments:

Campo	Tipo	Descripción
`internal_information.group_id`	string	ID del grupo, en el formato `120363430845284251-group`. Los grupos antiguos pueden venir en el formato `556592929755-1499690308`
`internal_information.group_name`	string	Nombre del grupo
`internal_information.participant_lid`	string	LID de quien envió el mensaje en el grupo, cuando la plataforma lo informa

En un mensaje recibido de un grupo, sender.identifier es el teléfono de quien escribió, no el del grupo. Los dos campos de grupo también aparecen cuando el mensaje se envía al grupo desde el propio número del canal (metadata.from_me: true). Los mensajes individuales no tienen group_id ni group_name.

"contents": [
  {
    "@class": ".TextContent",
    "internal_information": {
      "group_id": "120363430845284251-group",
      "group_name": "Equipo de ventas"
    },
    "message": "¡Buenos días a todos!",
    "type": "TEXT"
  }
]

En los webhooks con formato Z-API, enviados a los canales de Compatibilidad con Z-API, el mensaje recibido de un grupo sigue la estructura de Z-API: phone y chatName identifican el grupo, participantPhone y participantLid identifican a quien envió, y el callback de estado trae isGroup: true.

Tipos de contenido

El campo que diferencia el tipo de mensaje es @class, dentro de cada elemento de contents o attachments, combinado con el campo type.

TEXT — Mensaje de texto

El contenido está en contents[0] con type: "TEXT".

{
  "message": {
    "_id": "019E6F1A93FE78DCB54332F9FF0CCAE7",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980473342,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980473342
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".TextContent",
        "identifier": "019E6F1A93FE78DCB542303FF18D389A",
        "internal_information": {},
        "message": "¡Hola! ¿Qué tal? Tenemos novedades increíbles esperándote.",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A93FE78DCB5418E8D9D007FFB",
            "integration_message_ids": [],
            "moment": 1779980473342,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "TEXT"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}

IMAGE — Imagen con pie de foto

El adjunto está en attachments[0] con type: "IMAGE". El campo caption es opcional.

{
  "message": {
    "_id": "019E6F1A9553705584AD73DBA1F995A1",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980473683,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980473683
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [],
    "attachments": [
      {
        "@class": ".ImageAttachment",
        "caption": "¡Descubre nuestra línea de productos exclusivos!",
        "identifier": "019E6F1A9553705584AC33FB12CBAE6B",
        "internal_information": {},
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9553705584AB3D1D8510E8C3",
            "integration_message_ids": [],
            "moment": 1779980473683,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "thumbnail_url": "https://ejemplo.com/imagen-thumb.png",
        "type": "IMAGE",
        "url": "https://ejemplo.com/imagen.png"
      }
    ],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}

AUDIO — Mensaje de voz

El adjunto está en attachments[0] con type: "AUDIO".

{
  "message": {
    "_id": "019E6F1A96A7748489ECA59E6DCD8D63",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980474023,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980474023
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [],
    "attachments": [
      {
        "@class": ".AudioAttachment",
        "identifier": "019E6F1A96A7748489EBB11ED108DB51",
        "internal_information": {},
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A96A7748489EAC89D6BDBDD8A",
            "integration_message_ids": [],
            "moment": 1779980474023,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "AUDIO",
        "url": "https://ejemplo.com/audio.mp3"
      }
    ],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}

VIDEO — Vídeo con pie de vídeo

El adjunto está en attachments[0] con type: "VIDEO". El campo caption es opcional.

{
  "message": {
    "_id": "019E6F1A97F57A7BAFA0AF6D2ED9EA55",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980474357,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980474357
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [],
    "attachments": [
      {
        "@class": ".VideoAttachment",
        "caption": "¡Míralo y descubre cómo podemos ayudarte!",
        "identifier": "019E6F1A97F57A7BAF9F8945CDF9F269",
        "internal_information": {},
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A97F57A7BAF9E16EF4D180B18",
            "integration_message_ids": [],
            "moment": 1779980474357,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "VIDEO",
        "url": "https://ejemplo.com/video.mp4"
      }
    ],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}

STICKER — Sticker

El adjunto está en attachments[0] con type: "STICKER". La URL apunta a un archivo .webp.

{
  "message": {
    "_id": "019E6F1A9A8D74A097E650D75365502A",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980475021,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980475021
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [],
    "attachments": [
      {
        "@class": ".StickerAttachment",
        "identifier": "019E6F1A9A8D74A097E504E363C5809F",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9A8D74A097E4782F3FA0D805",
            "integration_message_ids": [],
            "moment": 1779980475021,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "STICKER",
        "url": "https://ejemplo.com/sticker.webp"
      }
    ],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}

CONTACT_ARRAY — Contacto(s)

El contenido está en contents[0] con type: "CONTACT_ARRAY". El array contacts puede contener varios contactos, cada uno con first_name, last_name, name y phones.

{
  "message": {
    "_id": "019E6F1A994975239E609D161623D3AD",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980474697,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980474697
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".ContactArrayContent",
        "contacts": [
          {
            "@class": ".ContactContent",
            "first_name": "Ryan",
            "identifier": "019E6F1A994975239E5E5BAF8C833D29",
            "last_name": "Andrade",
            "name": "Ryan Andrade",
            "phones": ["5544997294496"],
            "type": "CONTACT"
          }
        ],
        "identifier": "019E6F1A994975239E5FB79A31BFC0D8",
        "internal_information": {},
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A994975239E5D8A8C150F9F59",
            "integration_message_ids": [],
            "moment": 1779980474697,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "CONTACT_ARRAY"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}

INTERACTIVE_BUTTON — Botones de respuesta rápida (texto)

El contenido está en contents[0] con type: "INTERACTIVE_BUTTON". El campo internal_information.mediaButtonType indica el tipo de contenido multimedia adjunto: "TEXT" cuando no hay ninguno.

{
  "message": {
    "_id": "019E6F1A9D797F86B18E80700C3F22BD",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980475768,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980475768
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".InteractiveButtonContent",
        "buttons": [
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "1",
            "identifier": "019E6F1A9D78704094E6BF55E8608F62",
            "title": "Excelente",
            "type": "BUTTON"
          },
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "2",
            "identifier": "019E6F1A9D78704094E7458F381C4760",
            "title": "Bueno",
            "type": "BUTTON"
          },
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "3",
            "identifier": "019E6F1A9D78704094E8F88F236F2BDB",
            "title": "Regular",
            "type": "BUTTON"
          }
        ],
        "identifier": "019E6F1A9D797F86B18D0DE8252112B4",
        "internal_information": { "mediaButtonType": "TEXT" },
        "message": "¡Hola! ¿Cómo ha sido tu experiencia con nosotros?",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9D78704094E5ED1463943EF7",
            "integration_message_ids": [],
            "moment": 1779980475768,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "INTERACTIVE_BUTTON"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}

INTERACTIVE_BUTTON — Botones de respuesta rápida (con imagen)

Cuando internal_information.mediaButtonType es "IMAGE", el campo thumbnail contiene la URL de la imagen que se muestra encima de los botones.

{
  "message": {
    "_id": "019E6F1A9DDA7B3B92E8EF5955A33D3A",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980475864,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980475866
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".InteractiveButtonContent",
        "buttons": [
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "1",
            "identifier": "019E6F1A9DDA7B3B92E55FED919D3B46",
            "title": "Me interesa",
            "type": "BUTTON"
          },
          {
            "@class": "com.arkansas.littlerock.core.domain.content.ButtonContent",
            "id": "2",
            "identifier": "019E6F1A9DDA7B3B92E65ED03B1AA85C",
            "title": "No, gracias",
            "type": "BUTTON"
          }
        ],
        "identifier": "019E6F1A9DDA7B3B92E70CADB0034C76",
        "internal_information": { "mediaButtonType": "IMAGE" },
        "message": "¡Oferta especial solo para ti! Aprovéchala antes de que se acabe.",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9DDA7B3B92E43ADD4BB2FCE6",
            "integration_message_ids": [],
            "moment": 1779980475866,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "thumbnail": "https://ejemplo.com/imagen.png",
        "type": "INTERACTIVE_BUTTON"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}

INTERACTIVE_ACTION — Botones de acción (abrir URL y llamar)

El contenido está en contents[0] con type: "INTERACTIVE_ACTION". Cada botón de buttons tiene su propio type: "URL" o "CALL". Los campos header y footer son opcionales.

{
  "message": {
    "_id": "019E6F1A9BD8708EA5C67A9DBB071E68",
    "tenant": "019DCEB3E93B7077B2447616B6DC8B91",
    "tenant_owner": "email@z-api.io",
    "channel_id": "019E4C54B1B375A28970B605CA9B03C3",
    "created_by": "BARLING",
    "created": 1779980475352,
    "metadata": {
      "@class": ".Metadata",
      "forwarded": false,
      "from_api": true,
      "from_me": true,
      "middleware": "META_WHATSAPP",
      "moment": 1779980475352
    },
    "sender": {
      "@class": ".Sender",
      "identifier": "BARLING_SYSTEM",
      "name": "Barling System"
    },
    "recipient": {
      "@class": ".Recipient",
      "identifier": "5544936181064",
      "name": "5544936181064"
    },
    "contents": [
      {
        "@class": ".InteractiveActionContent",
        "action": {
          "@class": ".ActionContent",
          "identifier": "019E6F1A9BD8708EA5C4EFD19090B043",
          "type": "BUTTON"
        },
        "buttons": [
          {
            "@class": ".ButtonActionContent",
            "id": "1",
            "identifier": "019E6F1A9BD8708EA5C05038542872ED",
            "title": "Visita nuestro sitio web",
            "type": "URL",
            "url": "https://www.omni.z-api.io"
          },
          {
            "@class": ".ButtonActionContent",
            "id": "2",
            "identifier": "019E6F1A9BD8708EA5C1D19DAE30D4D0",
            "phone": "5544997294496",
            "title": "Llámanos",
            "type": "CALL"
          }
        ],
        "footer": {
          "@class": ".FooterContent",
          "identifier": "019E6F1A9BD8708EA5C315998956AE77",
          "message": "Elige una opción",
          "type": "BUTTON"
        },
        "header": {
          "@class": ".HeaderContent",
          "identifier": "019E6F1A9BD8708EA5C2D3033640052B",
          "message": "Omni Z-API",
          "type": "BUTTON"
        },
        "identifier": "019E6F1A9BD8708EA5C5ACAB2DFBD176",
        "internal_information": {},
        "message": "¿Cómo podemos ayudarte?",
        "state_items": [
          {
            "@class": ".StateItem",
            "identifier": "019E6F1A9BD8708EA5BF766A2E8F53A3",
            "integration_message_ids": [],
            "moment": 1779980475352,
            "state": { "@class": ".Pending", "name": "PENDING" }
          }
        ],
        "type": "INTERACTIVE_ACTION"
      }
    ],
    "attachments": [],
    "actions": [],
    "webhook_processed": false
  },
  "messageEventType": "NEW_MESSAGE"
}

Resumen de los tipos

`type`	Ubicación	Campo clave
`TEXT`	`contents[0]`	`message`
`IMAGE`	`attachments[0]`	`url`, `caption` (opcional), `thumbnail_url`
`AUDIO`	`attachments[0]`	`url`
`VIDEO`	`attachments[0]`	`url`, `caption` (opcional)
`STICKER`	`attachments[0]`	`url` (`.webp`)
`CONTACT_ARRAY`	`contents[0]`	`contacts[]` con `name`, `phones`
`INTERACTIVE_BUTTON`	`contents[0]`	`message`, `buttons[]`, `thumbnail` (si `mediaButtonType: "IMAGE"`)
`INTERACTIVE_ACTION`	`contents[0]`	`message`, `buttons[]` con `type: "URL"\|"CALL"`, `header`, `footer`

Canales

Mensajes

Plantillas (WhatsApp)

Flows (WhatsApp)

Webhooks

Estructura de los payloads

Envelope del evento

Campos comunes del mensaje

Mensajes de grupo (WhatsApp Web)

Tipos de contenido

TEXT — Mensaje de texto

IMAGE — Imagen con pie de foto

AUDIO — Mensaje de voz

VIDEO — Vídeo con pie de vídeo

STICKER — Sticker

CONTACT_ARRAY — Contacto(s)

INTERACTIVE_BUTTON — Botones de respuesta rápida (texto)

INTERACTIVE_BUTTON — Botones de respuesta rápida (con imagen)

INTERACTIVE_ACTION — Botones de acción (abrir URL y llamar)

Resumen de los tipos

​Envelope del evento

​Campos comunes del mensaje

​Mensajes de grupo (WhatsApp Web)

​Tipos de contenido

​TEXT — Mensaje de texto

​IMAGE — Imagen con pie de foto

​AUDIO — Mensaje de voz

​VIDEO — Vídeo con pie de vídeo

​STICKER — Sticker

​CONTACT_ARRAY — Contacto(s)

​INTERACTIVE_BUTTON — Botones de respuesta rápida (texto)

​INTERACTIVE_BUTTON — Botones de respuesta rápida (con imagen)

​INTERACTIVE_ACTION — Botones de acción (abrir URL y llamar)

​Resumen de los tipos

Envelope del evento

Campos comunes del mensaje

Mensajes de grupo (WhatsApp Web)

Tipos de contenido

TEXT — Mensaje de texto

IMAGE — Imagen con pie de foto

AUDIO — Mensaje de voz

VIDEO — Vídeo con pie de vídeo

STICKER — Sticker

CONTACT_ARRAY — Contacto(s)

INTERACTIVE_BUTTON — Botones de respuesta rápida (texto)

INTERACTIVE_BUTTON — Botones de respuesta rápida (con imagen)

INTERACTIVE_ACTION — Botones de acción (abrir URL y llamar)

Resumen de los tipos