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

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

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

​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

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