Ir para o conteúdo principal

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

  1. Webhooks de Status
  2. Mensagens Recebidas
  3. Mensagens de Grupo
  4. 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

  1. Campos Opcionais: Campos marcados como "pode ser null" podem não estar presentes no payload
  2. Formato de Números: Sempre no formato internacional sem símbolos (ex: 5511999999999)
  3. Timestamps: Formato Unix timestamp (segundos desde 1970)
  4. IDs: Todos os IDs são strings únicas geradas pelo provedor
  5. 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