Eventos Suportados

A plataforma MeChat dispara webhooks para os principais eventos do sistema. Você pode configurar quais eventos deseja receber.

Estrutura Base

Todos os payloads seguem esta estrutura:

json

{
  "event": "NOME_DO_EVENTO",
  "data": {},
  "timestamp": "2024-12-18T13:49:33+00:00",
  "attempt": 0,
  "webhook_id": "whk_675c1a2b3d4e5"
}

Campo	Descrição
event	Nome do evento disparado
data	Dados do evento (varia por tipo)
timestamp	Data/hora do evento (ISO8601)
attempt	Número da tentativa (0 = primeira)
webhook_id	ID único para rastreamento e deduplicação

Lista de Eventos

Evento	Descrição
`MESSAGE_SENT`	Mensagem enviada pela equipe
`MESSAGE_RECEIVED`	Mensagem recebida do contato
`CHAT_CREATED`	Nova conversa criada
`CHAT_ENDED`	Conversa finalizada
`CHAT_TRANSFERRED`	Conversa transferida
`CHANNEL_CONNECTED`	Canal conectado
`CHANNEL_DISCONNECTED`	Canal desconectado

Mensagens

MESSAGE_SENT

Disparado quando uma mensagem é enviada pela equipe para um contato.

Casos de uso:

Registrar mensagens enviadas em CRM externo
Atualizar histórico de atendimento
Sincronizar conversas com outros sistemas

json

{
  "event": "MESSAGE_SENT",
  "data": {
    "message": {
      "id": 12345,
      "content": "Olá, como posso ajudar?",
      "type": "text",
      "file": null,
      "direction": "outgoing",
      "visibility": "client",
      "created_at": "2024-12-18T13:55:00.000000Z"
    },
    "chat": {
      "token": "abc123def456",
      "status": "attending",
      "external_reference": null,
      "channel": {
        "token": "xyz789abc123def4",
        "name": "WhatsApp Atendimento",
        "type": "wppconnect"
      },
      "is_open": true,
      "unread_count": 0
    },
    "user": {
      "id": 5,
      "name": "Maria Silva",
      "email": "[email protected]",
      "avatar": "https://exemplo.com/avatars/5.jpg"
    },
    "contact": {
      "phone": "5531983064050",
      "name": "João Santos",
      "avatar": null,
      "blocked": false,
      "tags": [
        {
          "id": 1,
          "name": "VIP",
          "color": "#FF5733"
        }
      ]
    }
  },
  "timestamp": "2024-12-18T13:55:00+00:00",
  "attempt": 0,
  "webhook_id": "whk_675c1a2b3d4e5"
}

MESSAGE_RECEIVED

Disparado quando uma mensagem é recebida de um contato.

Casos de uso:

Criar tickets automáticos em sistema externo
Notificar equipe em outras plataformas
Integrar com chatbot externo

json

{
  "event": "MESSAGE_RECEIVED",
  "data": {
    "message": {
      "id": 12346,
      "content": "Preciso de ajuda com meu pedido",
      "type": "text",
      "file": null,
      "direction": "incoming",
      "visibility": "client",
      "created_at": "2024-12-18T13:56:00.000000Z"
    },
    "chat": {
      "token": "abc123def456",
      "status": "waiting",
      "external_reference": null,
      "channel": {
        "token": "xyz789abc123def4",
        "name": "WhatsApp Atendimento",
        "type": "wppconnect"
      },
      "is_open": true,
      "unread_count": 1
    },
    "user": null,
    "contact": {
      "phone": "5531983064050",
      "name": "João Santos",
      "avatar": null,
      "blocked": false,
      "tags": []
    }
  },
  "timestamp": "2024-12-18T13:56:00+00:00",
  "attempt": 0,
  "webhook_id": "whk_675c1a2b4e5f6"
}

Mensagem com Arquivo

Exemplo de mensagem enviada com imagem:

json

{
  "event": "MESSAGE_SENT",
  "data": {
    "message": {
      "id": 12347,
      "content": "https://exemplo.com/produto.jpg",
      "type": "image",
      "file": {
        "id": 456,
        "url": "https://exemplo.com/files/produto.jpg",
        "filename": "produto.jpg",
        "mimetype": "image/jpeg",
        "size": 245680
      },
      "direction": "outgoing",
      "visibility": "client",
      "created_at": "2024-12-18T13:57:00.000000Z"
    },
    "chat": {
      "token": "abc123def456",
      "status": "attending",
      "channel": {
        "token": "xyz789abc123def4",
        "name": "WhatsApp Vendas",
        "type": "wppconnect"
      }
    },
    "user": {
      "id": 8,
      "name": "Carlos Souza",
      "email": "[email protected]"
    },
    "contact": {
      "phone": "5531987654321",
      "name": "Ana Paula"
    }
  },
  "timestamp": "2024-12-18T13:57:00+00:00",
  "attempt": 0,
  "webhook_id": "whk_675c1a2c5f6g7"
}

Chats

CHAT_CREATED

Disparado quando uma nova conversa é criada.

Casos de uso:

Criar registro de atendimento em CRM
Notificar equipe sobre novo contato
Acionar workflows automáticos

json

{
  "event": "CHAT_CREATED",
  "data": {
    "chat": {
      "token": "abc123def456",
      "status": "waiting",
      "external_reference": null,
      "channel": {
        "token": "xyz789abc123def4",
        "name": "WhatsApp Atendimento",
        "type": "wppconnect"
      },
      "is_open": true,
      "unread_count": 0,
      "created_at": "2024-12-18T13:57:00.000000Z"
    },
    "contact": {
      "phone": "5531983064050",
      "name": "João Santos",
      "avatar": null,
      "blocked": false
    }
  },
  "timestamp": "2024-12-18T13:57:00+00:00",
  "attempt": 0,
  "webhook_id": "whk_675c1a2c5f6g7"
}

CHAT_ENDED

Disparado quando uma conversa é finalizada.

Casos de uso:

Fechar ticket em sistema externo
Enviar pesquisa de satisfação
Gerar relatórios

json

{
  "event": "CHAT_ENDED",
  "data": {
    "chat": {
      "token": "abc123def456",
      "status": "finalized",
      "external_reference": null,
      "channel": {
        "token": "xyz789abc123def4",
        "name": "WhatsApp Atendimento",
        "type": "wppconnect"
      },
      "is_open": false,
      "unread_count": 0,
      "ended_at": "2024-12-18T14:30:00.000000Z"
    },
    "contact": {
      "phone": "5531983064050",
      "name": "João Santos",
      "avatar": null,
      "blocked": false
    }
  },
  "timestamp": "2024-12-18T14:30:00+00:00",
  "attempt": 0,
  "webhook_id": "whk_675c1a2d6g7h8"
}

CHAT_TRANSFERRED

Disparado quando uma conversa é transferida para outro canal ou atendente.

Casos de uso:

Registrar histórico de transferências
Notificar novo responsável
Métricas de distribuição

json

{
  "event": "CHAT_TRANSFERRED",
  "data": {
    "chat": {
      "token": "abc123def456",
      "status": "waiting",
      "is_open": true,
      "unread_count": 0,
      "transferred_at": "2024-12-18T14:15:00.000000Z"
    },
    "contact": {
      "phone": "5531983064050",
      "name": "João Santos"
    },
    "from_channel": {
      "token": "xyz789abc123def4",
      "name": "WhatsApp Vendas",
      "type": "wppconnect"
    },
    "to_channel": {
      "token": "mno456pqr789stu0",
      "name": "WhatsApp Suporte",
      "type": "evolution"
    },
    "to_user": {
      "id": 8,
      "name": "Maria Silva",
      "email": "[email protected]"
    }
  },
  "timestamp": "2024-12-18T14:15:00+00:00",
  "attempt": 0,
  "webhook_id": "whk_675c1a40ab1cd2"
}

Canais

CHANNEL_CONNECTED

Disparado quando um canal é conectado com sucesso.

Casos de uso:

Notificar administradores sobre reconexão
Atualizar status em dashboard externo
Registrar uptime de canais

json

{
  "event": "CHANNEL_CONNECTED",
  "data": {
    "channel": {
      "token": "xyz789abc123def4",
      "name": "WhatsApp Atendimento",
      "type": "wppconnect",
      "status": "connected",
      "phone": "5531987654321",
      "connected_at": "2024-12-18T14:05:00.000000Z"
    }
  },
  "timestamp": "2024-12-18T14:05:00+00:00",
  "attempt": 0,
  "webhook_id": "whk_675c1a31ak1l2"
}

CHANNEL_DISCONNECTED

Disparado quando um canal perde conexão.

Casos de uso:

Alertar administradores sobre problema
Enviar notificação de urgência
Ativar canal backup

json

{
  "event": "CHANNEL_DISCONNECTED",
  "data": {
    "channel": {
      "token": "xyz789abc123def4",
      "name": "WhatsApp Atendimento",
      "type": "wppconnect",
      "status": "disconnected",
      "phone": "5531987654321",
      "disconnected_at": "2024-12-18T16:30:00.000000Z"
    }
  },
  "timestamp": "2024-12-18T16:30:00+00:00",
  "attempt": 0,
  "webhook_id": "whk_675c1a34dm3n5"
}

Estrutura dos Campos

message

Campo	Tipo	Descrição
id	integer	ID único da mensagem
content	string	Conteúdo da mensagem (texto ou URL do arquivo)
type	string	Tipo: `text`, `image`, `video`, `audio`, `document`, `sticker`, `vcard`, `ptt`
file	object/null	Dados do arquivo anexado
direction	string	`incoming` (recebida) ou `outgoing` (enviada)
visibility	string	`client` (visível para cliente) ou `internal` (apenas equipe)

chat

Campo	Tipo	Descrição
token	string	Token único do chat
status	string	Status: `waiting`, `attending`, `finalized`
external_reference	string/null	Referência externa personalizada
channel	object	Dados do canal
is_open	boolean	Se o chat está aberto
unread_count	integer	Mensagens não lidas

user

Campo	Tipo	Descrição
id	integer	ID do usuário
name	string	Nome do usuário
email	string	E-mail do usuário
avatar	string/null	URL do avatar

contact

Campo	Tipo	Descrição
phone	string	Telefone do contato
name	string	Nome do contato
avatar	string/null	URL do avatar
blocked	boolean	Se está bloqueado
tags	array	Tags do contato

file

Campo	Tipo	Descrição
id	integer	ID do arquivo
url	string	URL pública para download
filename	string	Nome do arquivo
mimetype	string	Tipo MIME
size	integer	Tamanho em bytes

Testando Eventos

Use ferramentas como gohook.io para testar:

Acesse o site e copie a URL única gerada
Configure essa URL no MeChat
Faça ações na plataforma
Veja os payloads chegando em tempo real

Como testar cada evento

Evento	Como testar
`MESSAGE_SENT`	Envie uma mensagem pelo painel
`MESSAGE_RECEIVED`	Envie mensagem do WhatsApp para o canal
`CHAT_CREATED`	Inicie conversa com novo número
`CHAT_ENDED`	Finalize uma conversa
`CHAT_TRANSFERRED`	Transfira conversa entre canais
`CHANNEL_CONNECTED`	Conecte um canal via QR Code
`CHANNEL_DISCONNECTED`	Desconecte um canal

Boas Práticas

Sempre valide o campo event antes de processar
Armazene o webhook_id para rastreamento e deduplicação
Trate campos null adequadamente
Para mensagens com arquivo, use file.url para download
Selecione apenas os eventos que realmente precisa
Use múltiplos webhooks para diferentes finalidades

Eventos Suportados ​

Estrutura Base ​

Lista de Eventos ​

Mensagens ​

MESSAGE_SENT ​

MESSAGE_RECEIVED ​

Mensagem com Arquivo ​

Chats ​

CHAT_CREATED ​

CHAT_ENDED ​

CHAT_TRANSFERRED ​

Canais ​

CHANNEL_CONNECTED ​

CHANNEL_DISCONNECTED ​

Estrutura dos Campos ​

message ​

chat ​

user ​

contact ​

file ​

Testando Eventos ​

Como testar cada evento ​

Boas Práticas ​

Eventos Suportados

Estrutura Base

Lista de Eventos

Mensagens

MESSAGE_SENT

MESSAGE_RECEIVED

Mensagem com Arquivo

Chats

CHAT_CREATED

CHAT_ENDED

CHAT_TRANSFERRED

Canais

CHANNEL_CONNECTED

CHANNEL_DISCONNECTED

Estrutura dos Campos

message

chat

user

contact

file

Testando Eventos

Como testar cada evento

Boas Práticas