Guia Completo de WebHooks

Enquanto os endpoints da API permitem que você envie comandos e mensagens, os webhooks são o mecanismo que permite que sua aplicação receba informações da plataforma Messagefy em tempo real. Eles são essenciais para criar aplicações interativas e responsivas, como chatbots e sistemas de monitoramento.

O que são WebHooks?

Webhooks são callbacks HTTP automáticos que nossa plataforma envia para uma URL de sua escolha (seu endpoint) sempre que um evento específico ocorre. Isso elimina a necessidade de sua aplicação consultar (fazer polling) nossos servidores constantemente em busca de novas informações.

Ao receber um webhook, sua aplicação deve retornar um código de status 200 OK para confirmar o recebimento. Qualquer outro status será interpretado como uma falha, e novas tentativas de entrega poderão ser realizadas.

Estrutura Geral dos WebHooks

Todos os webhooks seguem uma estrutura base consistente:

Campo	Tipo	Descrição
`packageId`	`string` (UUID v7)	Identificador único do pacote/webhook.
`channelId`	`string` (UUID)	Identificador do canal que gerou o evento.
`correlationId`	`string` ou `null`	ID de correlação para rastreamento (opcional).
`content`	`object`	Objeto contendo o conteúdo específico do webhook.
`timestamp`	`DateTimeOffset`	Data e hora em que o webhook foi gerado.
`providerMetadata`	`object` ou `null`	Metadados adicionais do provedor (opcional).
`echoMessage`	`bool` ou `null`	Retorna "true" quando é mensagem enviada de volta ao remetente (opcional).

O campo content contém sempre um campo type que identifica o tipo de webhook, além de campos específicos para cada tipo.

Tipos de WebHooks Suportados

A plataforma Messagefy envia dois tipos principais de webhooks: Eventos de Notificação e Mensagens Recebidas. Esta página detalha a estrutura e o propósito de cada um deles.

Resumo dos Tipos de WebHook

Para uma referência rápida, a tabela abaixo resume todos os tipos de webhooks que sua aplicação pode receber.

Categoria	Tipo (`content.type`)	Descrição Curta
Conexão	`INSTANCE_START`	Notifica que a instância do canal começou a iniciar.
	`CONNECTED`	Notifica que o canal está online e pronto para operar.
	`DISCONNECTED`	Alerta que o canal perdeu a conexão com o WhatsApp.
	`INSTANCE_STOP`	Notifica que a instância do canal foi explicitamente parada.
Autenticação	`GENERATE_QR_CODE_RESPONSE`	Entrega o QR Code em base64 para ser exibido ao usuário.
	`PAIR_CODE_GENERATED_RESPONSE`	Entrega um código de pareamento para autenticação manual.
Status de Mensagem	`MESSAGE_DELIVERED`	Confirma que uma mensagem enviada foi entregue ao destinatário.
	`MESSAGE_READ`	Confirma que uma mensagem enviada foi lida pelo destinatário.
	`MESSAGE_PLAYED`	Confirma que uma mídia (áudio/vídeo) foi reproduzida.
	`MESSAGE_DELETED`	Notifica que uma mensagem foi deletada por um participante.
	`MESSAGE_EDITED`	Notifica que uma mensagem foi editada por um participante.
Presença	`CONTACT_PRESENCE`	Notifica mudança de status online/offline de um contato inscrito.
Mensagens Recebidas	`TEXT`	Entrega uma mensagem de texto recebida de um usuário.
	`IMAGE`	Entrega uma mensagem de imagem recebida de um usuário.
	`VIDEO`	Entrega uma mensagem de vídeo recebida de um usuário.
	`AUDIO`	Entrega uma mensagem de áudio recebida de um usuário.
	`DOCUMENT`	Entrega um documento recebido de um usuário.
	`STICKER`	Entrega uma mensagem com sticker recebida de um usuário.
	`ORDER`	Entrega um pedido do catálogo do WhatsApp Business recebido de um cliente.
	`REACTION`	Entrega uma reação com emoji a uma mensagem anterior.

1. Eventos de Notificação

Estes eventos informam sobre o estado da conexão e o status de mensagens enviadas. Eles são essenciais para monitorar a saúde do seu canal e confirmar o sucesso das suas campanhas.

INSTANCE_START

Descrição: Notificação disparada quando a instância do canal começa o processo de inicialização. Obrigatória para confirmar sucesso na criação.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"INSTANCE_START"`.
`timestamp`	`DateTimeOffset`	Data e hora em que o evento ocorreu.

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789abc",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "INSTANCE_START",
    "timestamp": "2025-12-01T14:30:00.000+00:00"
  },
  "timestamp": "2025-12-01T14:30:00.100+00:00",
  "providerMetadata": null
}

CONNECTED

Descrição: Notificação disparada quando a instância do canal se conecta com sucesso ao WhatsApp.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"CONNECTED"`.
`timestamp`	`DateTimeOffset`	Data e hora em que o evento ocorreu.

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789abd",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "CONNECTED",
    "timestamp": "2025-12-01T14:30:05.000+00:00"
  },
  "timestamp": "2025-12-01T14:30:05.100+00:00",
  "providerMetadata": null
}

DISCONNECTED

Descrição: Notificação disparada quando a instância do canal perde a conexão com o WhatsApp.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"DISCONNECTED"`.
`timestamp`	`DateTimeOffset`	Data e hora em que o evento ocorreu.

Exemplo de Payload Completo

{
  "packageId": "019a124a-dc70-7e17-a993-3ae596a2535a",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "DISCONNECTED",
    "timestamp": "2025-10-23T18:18:07.2887636+00:00"
  },
  "timestamp": "2025-10-23T18:18:07.3450158+00:00",
  "providerMetadata": null
}

INSTANCE_STOP

Descrição: Notificação disparada quando a instância do canal é parada, seja por uma ação do usuário ou do sistema.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"INSTANCE_STOP"`.
`timestamp`	`DateTimeOffset`	Data e hora em que o evento ocorreu.

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789abe",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "INSTANCE_STOP",
    "timestamp": "2025-12-01T16:00:00.000+00:00"
  },
  "timestamp": "2025-12-01T16:00:00.100+00:00",
  "providerMetadata": null
}

GENERATE_QR_CODE_RESPONSE

Descrição: Entrega o QR Code necessário para autenticar o canal. Este webhook é enviado em resposta a uma solicitação de QR Code.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"GENERATE_QR_CODE_RESPONSE"`.
`success`	`boolean`	Indica se a geração do QR Code foi bem-sucedida.
`automatic`	`boolean`	Indica se o QR Code foi gerado automaticamente.
`qrCode`	`string`	O QR Code em formato data URI (base64).
`commandType`	`string`	Sempre `"GENERATE_QR_CODE_RESPONSE"`.
`timestamp`	`DateTimeOffset`	Data e hora em que o QR Code foi gerado.

Exemplo de Payload Completo

{
  "packageId": "019a126c-24f4-738e-b13c-a67576ae63a7",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "GENERATE_QR_CODE_RESPONSE",
    "success": true,
    "automatic": true,
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...RU5ErkJggg==",
    "commandType": "GENERATE_QR_CODE_RESPONSE",
    "timestamp": "2025-10-23T18:54:28.5725178+00:00"
  },
  "timestamp": "2025-10-23T18:54:28.5964372+00:00",
  "providerMetadata": null
}

PAIR_CODE_GENERATED_RESPONSE

Descrição: Entrega um código de pareamento como alternativa ao QR Code. Este código pode ser inserido manualmente no WhatsApp.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"PAIR_CODE_GENERATED_RESPONSE"`.
`success`	`boolean`	Indica se a geração do código foi bem-sucedida.
`pairCode`	`string`	O código de pareamento (formato: XXXX-XXXX).
`commandType`	`string`	Sempre `"PAIR_CODE_GENERATED_RESPONSE"`.
`timestamp`	`DateTimeOffset`	Data e hora em que o código foi gerado.

Exemplo de Payload Completo

{
  "packageId": "019a1248-c15e-7260-b87f-0a187484af71",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "PAIR_CODE_GENERATED_RESPONSE",
    "success": true,
    "pairCode": "HTNK-GFF5",
    "commandType": "PAIR_CODE_GENERATED_RESPONSE",
    "timestamp": "2025-10-23T18:15:49.3038651+00:00"
  },
  "timestamp": "2025-10-23T18:15:49.34475+00:00",
  "providerMetadata": null
}

MESSAGE_DELIVERED

Descrição: Confirma que uma mensagem enviada foi entregue ao dispositivo do destinatário.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"MESSAGE_DELIVERED"`.
`messageIds`	`string[]`	Lista de IDs das mensagens que foram entregues.
`timestamp`	`DateTimeOffset`	Data e hora em que o evento ocorreu.

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789abf",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "MESSAGE_DELIVERED",
    "messageIds": ["3EB08209536937A66D8434"],
    "timestamp": "2025-12-01T14:31:00.000+00:00"
  },
  "timestamp": "2025-12-01T14:31:00.100+00:00",
  "providerMetadata": null
}

MESSAGE_READ

Descrição: Confirma que uma mensagem enviada foi lida (visualizada) pelo destinatário.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"MESSAGE_READ"`.
`messageIds`	`string[]`	Lista de IDs das mensagens que foram lidas.
`timestamp`	`DateTimeOffset`	Data e hora em que o evento ocorreu.

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789ac0",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "MESSAGE_READ",
    "messageIds": ["3EB08209536937A66D8434"],
    "timestamp": "2025-12-01T14:31:05.000+00:00"
  },
  "timestamp": "2025-12-01T14:31:05.100+00:00",
  "providerMetadata": null
}

MESSAGE_PLAYED

Descrição: Confirma que uma mensagem de áudio ou vídeo enviada foi reproduzida pelo destinatário.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"MESSAGE_PLAYED"`.
`messageIds`	`string[]`	Lista de IDs das mídias que foram reproduzidas.
`timestamp`	`DateTimeOffset`	Data e hora em que o evento ocorreu.

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789ac1",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "MESSAGE_PLAYED",
    "messageIds": ["3EB08209536937A66D8435"],
    "timestamp": "2025-12-01T14:31:10.000+00:00"
  },
  "timestamp": "2025-12-01T14:31:10.100+00:00",
  "providerMetadata": null
}

MESSAGE_DELETED

Descrição: Notifica que uma mensagem foi deletada por um dos participantes da conversa.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"MESSAGE_DELETED"`.
`messageId`	`string`	ID da mensagem que foi deletada.
`chatId`	`string`	ID do chat ou grupo onde a mensagem foi deletada.
`isFromMe`	`boolean`	`true` se a mensagem deletada foi enviada pelo próprio remetente.
`timestamp`	`DateTimeOffset`	Data e hora em que o evento ocorreu.

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789ac2",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "MESSAGE_DELETED",
    "messageId": "3EB08209536937A66D8434",
    "chatId": "5511999998888@s.whatsapp.net",
    "isFromMe": false,
    "timestamp": "2025-12-01T14:32:00.000+00:00"
  },
  "timestamp": "2025-12-01T14:32:00.100+00:00",
  "providerMetadata": null
}

MESSAGE_EDITED

Descrição: Notifica que uma mensagem de texto foi editada por um dos participantes da conversa.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"MESSAGE_EDITED"`.
`messageId`	`string`	ID da mensagem original que foi editada.
`newMessageId`	`string` ou `null`	Novo ID da mensagem após edição.
`chatId`	`string`	ID do chat ou grupo onde a mensagem foi editada.
`newText`	`string`	O novo conteúdo de texto da mensagem.
`isFromMe`	`boolean`	`true` se a mensagem editada foi enviada pelo próprio remetente.
`timestamp`	`DateTimeOffset`	Data e hora em que o evento ocorreu.

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789ac3",
  "channelId": "019a1244-fd19-7d12-b9d5-99be1d1acd83",
  "correlationId": null,
  "content": {
    "type": "MESSAGE_EDITED",
    "messageId": "3EB08209536937A66D8434",
    "newMessageId": "3EB08209536937A66D8435",
    "chatId": "5511999998888@s.whatsapp.net",
    "newText": "Texto corrigido da mensagem",
    "isFromMe": false,
    "timestamp": "2025-12-01T14:33:00.000+00:00"
  },
  "timestamp": "2025-12-01T14:33:00.100+00:00",
  "providerMetadata": null
}

CONTACT_PRESENCE

Descrição: Notifica que um contato inscrito mudou de status (online/offline).

Sobre a inscrição de presença

A inscrição de presença é feita por contato e está vinculada à sessão ativa do WhatsApp. Ao receber um evento CONNECTED, todas as inscrições anteriores são invalidadas e devem ser refeitas. O WhatsApp pode silenciosamente deixar de enviar atualizações após um período de inatividade (5~10 minutos), se isso ocorrer, uma nova requisição de inscrição deverá ser feita.

Estrutura do content

Campo	Tipo	Descrição
`type`	`string`	Sempre `"CONTACT_PRESENCE"`.
`jid`	`string` ou `null`	Id do contato.
`lid`	`string` ou `null`	Id do contato.
`unavailable`	`boolean`	`true` = contato offline, `false` = contato online.
`lastSeen`	`string` (ISO 8601) ou `null`	Data/hora do último acesso do contato. Geralmente preenchido apenas quando o contato fica offline.
`timestamp`	`DateTimeOffset`	Momento do evento no WhatsApp.

Nota sobre identificadores: Eventos de presença podem chegar identificados por JID OU LID, mas nunca os dois. Na grande maioria das vezes, o identificador retornado pelo WhatsApp é o LID.

Exemplo de Payload — Contato ficou online

{
  "packageId": "019c0b3e-8b86-758a-8b66-89be17268466",
  "channelId": "019c0653-b625-710f-87dc-4d2cbfee0fd2",
  "correlationId": null,
  "content": {
    "type": "CONTACT_PRESENCE",
    "jid": "5511999998888@s.whatsapp.net",
    "lid": "271283019378755@lid",
    "unavailable": false,
    "lastSeen": null,
    "timestamp": "2026-02-06T14:30:00.0000000+00:00"
  },
  "timestamp": "2026-02-06T14:30:00.0500000+00:00",
  "providerMetadata": null
}

Exemplo de Payload — Contato ficou offline

{
  "packageId": "019c0b52-1aee-7979-8d40-cfac195675f6",
  "channelId": "019c0653-b625-710f-87dc-4d2cbfee0fd2",
  "correlationId": null,
  "content": {
    "type": "CONTACT_PRESENCE",
    "jid": "5511999998888@s.whatsapp.net",
    "lid": "271283019378755@lid",
    "unavailable": true,
    "lastSeen": "2026-02-06T14:45:00Z",
    "timestamp": "2026-02-06T14:45:00.0000000+00:00"
  },
  "timestamp": "2026-02-06T14:45:00.0500000+00:00",
  "providerMetadata": null
}

2. Mensagens Recebidas

Estes webhooks entregam o conteúdo que os usuários enviam para o seu canal do WhatsApp.

Estrutura Comum de Mensagens Recebidas

Todos os webhooks de mensagens recebidas compartilham campos comuns dentro do objeto content:

Campo	Tipo	Descrição
`type`	`string`	O tipo da mensagem (`TEXT`, `IMAGE`, `VIDEO`, etc.).
`messageId`	`string`	ID único da mensagem recebida.
`from`	`object`	Detalhes do remetente.
`from.type`	`string`	Sempre `"WHATSAPP"`.
`from.id`	`string`	Identificador único do remetente (JID).
`from.number`	`string`	Número do remetente (sem formatação).
`from.name`	`string`	Nome do remetente.
`to`	`object`	Detalhes do destinatário (seu canal).
`to.type`	`string`	Sempre `"WHATSAPP"`.
`to.id`	`string`	Identificador único do destinatário (JID).
`to.number`	`string`	Número do destinatário.
`to.name`	`string`	Nome do destinatário.
`isFromMe`	`boolean`	Sempre `false` para mensagens recebidas.
`isForwarded`	`boolean`	`true` se a mensagem foi encaminhada.
`isGroupMessage`	`boolean`	`true` se a mensagem foi enviada em um grupo.
`senderName`	`string` ou `null`	Nome do remetente no contexto de grupo.
`deliveryStrategy`	`integer`	Estratégia de entrega (geralmente `0`).
`priority`	`integer`	Prioridade da mensagem (geralmente `0`).
`deliveryDeadline`	`string` ou `null`	Prazo de entrega (opcional).
`timestamp`	`DateTimeOffset`	Data e hora em que a mensagem foi enviada.
`quotedMessage`	`object`	Dados da mensagem citada (resposta). Só está presente quando a mensagem é uma resposta a outra.
`isStatusMessage`	`boolean`	`true` se a mensagem for proveniente de um Status (Atualizações).

Mensagens com Citação (Respostas)

Quando um usuário responde a uma mensagem, o campo quotedMessage estará presente contendo informações sobre a mensagem original.

Estrutura do quotedMessage

Campo	Tipo	Descrição
`messageId`	`string`	ID da mensagem original que está sendo citada.
`participant`	`string`	Id do remetente da mensagem citada. Pode estar no formato `551199999999@s.whatsapp.net` ou `1111111111@lid`.

Além desses campos, cada tipo de mensagem possui campos específicos no objeto content.

TEXT

Descrição: Entrega uma mensagem de texto simples.

Campos Específicos do content

Campo	Tipo	Descrição
`text`	`string`	O conteúdo da mensagem de texto.

Exemplo de Payload Completo

{
  "packageId": "019a129d-06ad-74bc-9543-bcc030a38169",
  "channelId": "019a1258-177c-7286-b060-9ee02a0800c7",
  "correlationId": null,
  "content": {
    "type": "TEXT",
    "text": "Hello World!",
    "from": {
      "type": "WHATSAPP",
      "id": "179508325961790@lid",
      "number": "179508325961790",
      "name": "Ivson"
    },
    "to": {
      "type": "WHATSAPP",
      "id": "120363402110764959@g.us",
      "number": "120363402110764959",
      "name": "Messagefy"
    },
    "messageId": "3EB08209536937A66D8434",
    "isFromMe": false,
    "isForwarded": false,
    "isGroupMessage": true,
    "senderName": null,
    "quotedMessage": {
      "messageId": "3EB08209536937A66D8430",
      "participant": "5511988887777@s.whatsapp.net"
    },
    "deliveryStrategy": 0,
    "priority": 0,
    "deliveryDeadline": null,
    "isStatusMessage": false,
    "timestamp": "2025-10-23T19:47:51+00:00"
  },
  "timestamp": "2025-10-23T19:47:52.1095029+00:00",
  "providerMetadata": null
}

IMAGE

Descrição: Entrega uma mensagem de imagem.

Campos Específicos do content

Campo	Tipo	Descrição
`downloadHash`	`string`	Hash para fazer o download da imagem.
`caption`	`string` ou `null`	Legenda da imagem (opcional).
`filename`	`string`	Nome do arquivo da imagem.
`mimetype`	`string`	Tipo MIME da imagem (ex: `image/jpeg`).

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789ac2",
  "channelId": "019a1258-177c-7286-b060-9ee02a0800c7",
  "correlationId": null,
  "content": {
    "type": "IMAGE",
    "downloadHash": "abc123def456",
    "caption": "Olha essa foto!",
    "filename": "foto_produto.jpg",
    "mimetype": "image/jpeg",
    "from": {
      "type": "WHATSAPP",
      "id": "5511999998888@s.whatsapp.net",
      "number": "5511999998888",
      "name": "Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "id": "5511988887777@s.whatsapp.net",
      "number": "5511988887777",
      "name": "Minha Empresa"
    },
    "messageId": "3EB08209536937A66D8435",
    "isFromMe": false,
    "isForwarded": false,
    "isGroupMessage": false,
    "senderName": null,
    "quotedMessage": {
      "messageId": "3EB08209536937A66D8432",
      "participant": "5511988887777@s.whatsapp.net"
    },
    "deliveryStrategy": 0,
    "priority": 0,
    "deliveryDeadline": null,
    "isStatusMessage": false,
    "timestamp": "2025-12-01T14:36:00+00:00"
  },
  "timestamp": "2025-12-01T14:36:00.100+00:00",
  "providerMetadata": null
}

VIDEO

Descrição: Entrega uma mensagem de vídeo.

Campos Específicos do content

Campo	Tipo	Descrição
`downloadHash`	`string`	Hash para fazer o download do vídeo.
`caption`	`string` ou `null`	Legenda do vídeo (opcional).
`filename`	`string`	Nome do arquivo do vídeo.
`mimetype`	`string`	Tipo MIME do vídeo (ex: `video/mp4`).

AUDIO

Descrição: Entrega uma mensagem de áudio.

Campos Específicos do content

Campo	Tipo	Descrição
`downloadHash`	`string`	Hash para fazer o download do áudio.
`filename`	`string`	Nome do arquivo de áudio.
`mimetype`	`string`	Tipo MIME do áudio (ex: `audio/ogg`).

DOCUMENT

Descrição: Entrega uma mensagem com um documento anexo.

Campos Específicos do content

Campo	Tipo	Descrição
`downloadHash`	`string`	Hash para fazer o download do documento.
`caption`	`string` ou `null`	Legenda do documento (opcional).
`filename`	`string`	Nome do arquivo do documento.
`mimetype`	`string`	Tipo MIME do documento (ex: `application/pdf`).

STICKER

Descrição: Entrega uma mensagem de sticker.

Campos Específicos do content

Campo	Tipo	Descrição
`downloadHash`	`string`	Hash para fazer o download da imagem.
`filename`	`string`	Nome do arquivo de imagem.
`mimetype`	`string`	Tipo MIME da imagem (ex: `image/webp`).

REACTION

Descrição: Entrega uma reação com emoji a uma mensagem anterior.

Campos Específicos do content

Campo	Tipo	Descrição
`emoji`	`string`	O emoji da reação (ex: "👍").
`targetMessageId`	`string`	O ID da mensagem que recebeu a reação.

Exemplo de Payload Completo

{
  "packageId": "019a1234-5678-7abc-def0-123456789ac3",
  "channelId": "019a1258-177c-7286-b060-9ee02a0800c7",
  "correlationId": null,
  "content": {
    "type": "REACTION",
    "emoji": "👍",
    "targetMessageId": "3EB08209536937A66D8434",
    "from": {
      "type": "WHATSAPP",
      "id": "5511999998888@s.whatsapp.net",
      "number": "5511999998888",
      "name": "Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "id": "5511988887777@s.whatsapp.net",
      "number": "5511988887777",
      "name": "Minha Empresa"
    },
    "messageId": "3EB08209536937A66D8436",
    "isFromMe": false,
    "isGroupMessage": false,
    "senderName": null,
    "deliveryStrategy": 0,
    "priority": 0,
    "deliveryDeadline": null,
    "isStatusMessage": false,
    "timestamp": "2025-12-01T14:37:00+00:00"
  },
  "timestamp": "2025-12-01T14:37:00.100+00:00",
  "providerMetadata": null
}

ORDER

Descrição: Entrega um pedido do catálogo do WhatsApp Business. Pedidos são enviados quando um cliente seleciona produtos do catálogo e envia um pedido pelo WhatsApp.

Campos Específicos do content

Campo	Tipo	Descrição
`orderId`	`string`	Identificador único do pedido no WhatsApp.
`itemCount`	`integer`	Quantidade total de itens no pedido.
`totalAmount1000`	`integer`	Valor total do pedido em milésimos. Divida por 1000 para obter o valor real (ex: `13500` = R$ 13,50).
`totalCurrencyCode`	`string`	Código da moeda (ex: `BRL`, `USD`).
`text`	`string` ou `null`	Mensagem opcional enviada pelo cliente junto ao pedido.
`thumbnail`	`string` ou `null`	Thumbnail do pedido em base64 (JPEG).
`items`	`array`	Lista de produtos do pedido.

Estrutura de cada item em items

Campo	Tipo	Descrição
`name`	`string`	Nome do produto.
`quantity`	`integer`	Quantidade solicitada.
`price`	`integer`	Preço unitário em milésimos. Divida por 1000 para obter o valor real (ex: `8500` = R$ 8,50).
`currency`	`string`	Código da moeda do item (ex: `BRL`).
`imageUrl`	`string` ou `null`	URL da imagem do produto no StorageFy. Veja nota sobre disponibilidade abaixo.

Nota sobre imagens de produtos: As URLs em items[].imageUrl são presigned URLs do StorageFy. Quando o pedido é recebido, as imagens ainda podem estar em processamento. Um evento DOWNLOAD_AVAILABLE será enviado para cada imagem quando ela estiver pronta para download. O campo externalDownloadUrl do DOWNLOAD_AVAILABLE corresponde ao imageUrl do item.

Exemplo de Payload Completo

{
  "packageId": "019d3bff-efb4-7566-9901-cfb29dde3ed5",
  "channelId": "019d3bfd-d884-71d4-b162-218d70dee00f",
  "organizationID": "019d3bfc-0470-740b-b53d-5fc1d0c88f36",
  "accountId": "019d3bfc-0594-79c9-8565-2f02ce381a75",
  "correlationId": null,
  "content": {
    "type": "ORDER",
    "orderId": "1895184554485465",
    "itemCount": 3,
    "totalAmount1000": 13500,
    "totalCurrencyCode": "BRL",
    "text": "",
    "thumbnail": "/9j/4AAQSkZJRgABAQAA...",
    "items": [
      {
        "name": "Garrafa de água",
        "quantity": 2,
        "price": 2500,
        "currency": "BRL",
        "imageUrl": "https://storage-dev.messagefy.io/api/v1/files/download-external/abc123"
      },
      {
        "name": "Refrigerante",
        "quantity": 1,
        "price": 8500,
        "currency": "BRL",
        "imageUrl": "https://storage-dev.messagefy.io/api/v1/files/download-external/def456"
      }
    ],
    "from": {
      "type": "WHATSAPP",
      "jid": "554298002650@s.whatsapp.net",
      "lid": "28209462644963@lid",
      "number": "554298002650",
      "name": "Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "554288706357@s.whatsapp.net",
      "number": "554288706357",
      "name": "Minha Loja"
    },
    "messageId": "3A8BEC9A4AF0FC7264AE",
    "isFromMe": false,
    "isGroupMessage": false,
    "isForwarded": false,
    "isStatusMessage": false,
    "deliveryStrategy": 0,
    "priority": 0,
    "timestamp": "2026-03-29T23:48:42+00:00"
  },
  "timestamp": "2026-03-29T23:48:42.0366555+00:00",
  "providerMetadata": null
}

Como Configurar seu Endpoint de WebHook

Crie um Endpoint em sua Aplicação: Desenvolva uma rota (URL) em seu servidor que seja capaz de receber requisições POST.

Crie um Canal de Webhook: Utilize o endpoint POST /api/admin/channel para registrar a URL do seu servidor em nossa plataforma, você encontra na sessão canais na ação Criar Canal de webhook

Processe os Dados: Sua aplicação receberá um payload JSON contendo os detalhes do evento. Certifique-se de retornar um status 200 OK para confirmar o recebimento.

Valide o Tipo: Use o campo content.type para determinar qual tipo de webhook foi recebido e processar adequadamente.

O que são WebHooks?#

Estrutura Geral dos WebHooks#

Tipos de WebHooks Suportados#

Resumo dos Tipos de WebHook#

1. Eventos de Notificação#

INSTANCE_START#

CONNECTED#

DISCONNECTED#

INSTANCE_STOP#

GENERATE_QR_CODE_RESPONSE#

PAIR_CODE_GENERATED_RESPONSE#

MESSAGE_DELIVERED#

MESSAGE_READ#

MESSAGE_PLAYED#

MESSAGE_DELETED#

MESSAGE_EDITED#

CONTACT_PRESENCE#

2. Mensagens Recebidas#

Estrutura Comum de Mensagens Recebidas#

Mensagens com Citação (Respostas)#

TEXT#

IMAGE#

VIDEO#

AUDIO#

DOCUMENT#

STICKER#

REACTION#

ORDER#

Como Configurar seu Endpoint de WebHook#

O que são WebHooks?

Estrutura Geral dos WebHooks

Tipos de WebHooks Suportados

Resumo dos Tipos de WebHook

1. Eventos de Notificação

INSTANCE_START

CONNECTED

DISCONNECTED

INSTANCE_STOP

GENERATE_QR_CODE_RESPONSE

PAIR_CODE_GENERATED_RESPONSE

MESSAGE_DELIVERED

MESSAGE_READ

MESSAGE_PLAYED

MESSAGE_DELETED

MESSAGE_EDITED

CONTACT_PRESENCE

2. Mensagens Recebidas

Estrutura Comum de Mensagens Recebidas

Mensagens com Citação (Respostas)

TEXT

IMAGE

VIDEO

AUDIO

DOCUMENT

STICKER

REACTION

ORDER

Como Configurar seu Endpoint de WebHook