Tipos de webhooks e mensagens recebidos

Documentação Completa - WhatsApp Web API

Visão Geral

Este documento descreve todos os tipos de status e mensagens possíveis de serem recebidos no Omnichannel, incluindo suas estruturas de dados e informações.

Índice

Webhooks de Status

Mensagens Recebidas

Mensagens de Grupo

Reações a Mensagens

Webhooks de Status

1. MESSAGE_UPDATE

Atualização de status de mensagens enviadas ou recebidas.

1.1. Status de Entrega

Tipo: MESSAGE_UPDATE

Payload:

{
  "platformConfigId": "string",
  "channelId": "string",
  "type": "MESSAGE_UPDATE",
  "payload": {
    "message": {
      "from": "5511999999999",
      "to": "5511888888888",
      "providerId": "5511999999999",
      "messageId": "message_unique_id",
      "status": "SENDED | DELIVERED | READED"
    }
  }
}

Campos:

from: Número do remetente (formato: DDI + DDD + número)

to: Número do destinatário (formato: DDI + DDD + número)

providerId: Número conectado

messageId: ID único da mensagem

status: Status da mensagem

Status Possíveis:

SENDED: Mensagem enviada ao servidor do WhatsApp

DELIVERED: Mensagem entregue ao destinatário

READED: Mensagem lida pelo destinatário

1.2. Mensagem Editada

Tipo: MESSAGE_UPDATE

Payload:

{
  "platformConfigId": "string",
  "channelId": "string",
  "type": "MESSAGE_UPDATE",
  "payload": {
    "message": {
      "from": "5511999999999",
      "to": "5511888888888",
      "providerId": "5511888888888",
      "messageId": "message_unique_id",
      "status": "EDITED",
      "content": "Novo conteúdo da mensagem editada",
      "messageTimestamp": "1234567890"
    }
  }
}

Campos:

from: Número do remetente

to: Número do destinatário

providerId: Número conectado

messageId: ID único da mensagem editada

status: Sempre EDITED

content: Novo texto da mensagem após edição

messageTimestamp: Timestamp da edição

1.3. Mensagem Removida

Tipo: MESSAGE_UPDATE

Payload:

{
  "platformConfigId": "string",
  "channelId": "string",
  "type": "MESSAGE_UPDATE",
  "payload": {
    "message": {
      "from": "5511999999999",
      "to": "5511888888888",
      "providerId": "5511888888888",
      "messageId": "message_unique_id",
      "status": "REMOVED",
      "messageTimestamp": "1234567890"
    }
  }
}

Campos:

from: Número do remetente

to: Número do destinatário

providerId: Número conectado

messageId: ID único da mensagem removida

status: Sempre REMOVED

messageTimestamp: Timestamp da remoção

2. CONNECTION_UPDATE

Atualização do status de conexão da conta WhatsApp.

Tipo: CONNECTION_UPDATE

Payload:

{
  "platformConfigId": "string",
  "channelId": "string",
  "type": "CONNECTION_UPDATE",
  "payload": {
    "connection": {
      "providerId": "5511888888888",
      "status": "open | close",
      "isOnline": true
    }
  }
}

Campos:

providerId: Número conectado

status: Status da conexão
- open: Conexão ativa
- close: Conexão encerrada

isOnline: Booleano indicando se está online (true quando status = 'open')

Uso: Essencial para o Chat Enterprise monitorar disponibilidade da conexão.

3. CONTACTS_IMPORT

Importação de contatos da agenda do WhatsApp.

Tipo: CONTACTS_IMPORT

Payload:

{
  "platformConfigId": "string",
  "channelId": "string",
  "type": "CONTACTS_IMPORT",
  "payload": {
    "contacts": [
      {
        "name": "Nome do Contato",
        "providerName": "Nome no WhatsApp",
        "number": "5511999999999",
        "email": "contato@email.com",
        "foto": "https://s3.url/foto.jpg",
        "type": "individual | group"
      }
    ]
  }
}

Campos do Contato:

name: Nome salvo na agenda (pode ser null)

providerName: Nome definido no WhatsApp (pode ser null)

number: Número do contato (formato: DDI + DDD + número)

email: Email do contato (pode ser null)

foto: URL da foto de perfil no S3 (pode ser null)

type: Tipo do contato
- individual: Contato pessoal
- group: Grupo do WhatsApp

Resumo dos Status de Mensagem

Status	Descrição	Quando Ocorre
`SENDED`	Enviada	Mensagem chegou ao servidor WhatsApp
`DELIVERED`	Entregue	Mensagem chegou ao dispositivo do destinatário
`READED`	Lida	Destinatário abriu e leu a mensagem
`EDITED`	Editada	Remetente editou o conteúdo da mensagem
`REMOVED`	Removida	Remetente apagou a mensagem

Resumo dos Tipos de Webhook

Tipo	Descrição	Frequência
`MESSAGE_UPDATE`	Atualizações de mensagens	Alta - a cada mudança de status
`CONNECTION_UPDATE`	Status da conexão	Média - quando conecta/desconecta
`CONTACTS_IMPORT`	Importação de contatos	Baixa - na sincronização inicial

Observações Importantes

Campos Opcionais: Campos marcados como "pode ser null" podem não estar presentes no payload

Formato de Números: Sempre no formato internacional sem símbolos (ex: 5511999999999)

Timestamps: Formato Unix timestamp (segundos desde 1970)

IDs: Todos os IDs são strings únicas geradas pelo provedor

Connection Status: O campo isOnline é crítico para o Chat Enterprise

Exemplos de Uso

Rastreamento de Mensagem

SENDED → DELIVERED → READED

Ciclo de Vida da Conexão

CONNECTION_UPDATE (status: open) → ... → CONNECTION_UPDATE (status: close)

Sincronização de Contatos

CONTACTS_IMPORT (array com todos os contatos)

Mensagens Recebidas

MESSAGE (Mensagem Individual)

Mensagens recebidas de conversas individuais (1:1).

Tipo: MESSAGE

Payload:

{
  "uid": "message_unique_id",
  "sessionId": "session_object_id",
  "platformConfigId": "platform_config_id",
  "channelId": "channel_id",
  "from": {
    "uid": "5511999999999",
    "userName": "Nome do Contato"
  },
  "message": {
    "body": "Texto da mensagem"
  },
  "source": "whatsappweb",
  "type": "MESSAGE"
}

Campos Obrigatórios:

uid: ID único da mensagem

sessionId: ID da sessão ativa

platformConfigId: ID da configuração da plataforma

channelId: ID do canal

from.uid: Número do remetente

from.userName: Nome do remetente

message.body: Conteúdo da mensagem (texto, caption ou vazio)

source: Sempre whatsappweb

type: Sempre MESSAGE

Campos Opcionais:

Mídia (Arquivo)

"message": {
  "body": "Legenda do arquivo",
  "media": {
    "contentType": "image/jpeg",
    "uri": "https://s3.url/arquivo.jpg",
    "fileName": ""
  }
}

media.contentType: Tipo MIME do arquivo (image/jpeg, video/mp4, audio/ogg, etc.)

media.uri: URL do arquivo no S3

media.fileName: Nome do arquivo (geralmente vazio)

Localização

"location": {
  "latitude": -23.550520,
  "longitude": -46.633308
}

latitude: Coordenada de latitude

longitude: Coordenada de longitude

Contatos Compartilhados

"contacts": [
  {
    "name": "Nome do Contato",
    "phone": "5511888888888"
  }
]

Array de contatos compartilhados na mensagem

Mensagem Citada (Reply)

"message": {
  "body": "Resposta",
  "quoted": {
    "id": "quoted_message_id"
  }
}

quoted.id: ID da mensagem que está sendo respondida

Observação: O campo text com valor "Arquivo" é ignorado e substituído por caption ou string vazia.

Mensagens de Grupo

GROUP_MESSAGE

Mensagens recebidas de grupos do WhatsApp.

Tipo: GROUP_MESSAGE

Payload:

{
  "uid": "message_unique_id",
  "sessionId": null,
  "platformConfigId": "platform_config_id",
  "channelId": "channel_id",
  "from": {
    "uid": "5511999999999@g.us",
    "userName": "Nome do Grupo",
    "participant": "5511888888888"
  },
  "message": {
    "body": "Texto da mensagem"
  },
  "source": "whatsappweb",
  "type": "GROUP_MESSAGE"
}

Diferenças em relação a MESSAGE:

sessionId: Sempre null (grupos não têm sessão)

from.uid: ID do grupo (termina com @g.us)

from.participant: Número do participante que enviou a mensagem

Campos Opcionais: Mesmos de MESSAGE (mídia, localização, contatos, quoted)

Uso: Permite identificar mensagens de grupos e qual participante enviou.

Reações a Mensagens

MESSAGE_REACTION

Reações (emojis) adicionadas a mensagens.

Tipo: MESSAGE_REACTION

Payload:

{
  "uid": "reaction_key_id",
  "sessionId": null,
  "platformConfigId": "platform_config_id",
  "channelId": "channel_id",
  "from": {
    "uid": "5511999999999"
  },
  "reaction": {
    "selectedMessageId": "target_message_id",
    "emoji": "👍"
  },
  "source": "whatsappweb",
  "type": "MESSAGE_REACTION"
}

Campos:

uid: ID da chave da reação

sessionId: Sempre null

from.uid: Número de quem reagiu

from.participant: (Opcional) Presente se for reação em grupo

reaction.selectedMessageId: ID da mensagem que recebeu a reação

reaction.emoji: Emoji da reação (ex: 👍, ❤️, 😂)

Remoção de Reação: Quando uma reação é removida, o campo emoji vem vazio:

"reaction": {
  "selectedMessageId": "target_message_id",
  "emoji": ""
}

Resumo dos Tipos de Webhook

Tipo	Descrição	sessionId	Uso
`MESSAGE`	Mensagem individual	Presente	Conversas 1:1
`GROUP_MESSAGE`	Mensagem de grupo	null	Grupos WhatsApp
`MESSAGE_REACTION`	Reação a mensagem	null	Emojis em mensagens
`MESSAGE_UPDATE`	Status de mensagem	-	Entrega/Leitura/Edição
`CONNECTION_UPDATE`	Status de conexão	-	Monitoramento
`CONTACTS_IMPORT`	Importação de contatos	-	Sincronização