Eventos Suportados

Disparamos webhooks para os principais eventos do sistema. Você pode configurar quais eventos deseja receber.

Estrutura Base

Todos os payloads que enviamos seguem esta estrutura:

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

Campo	Descrição
event	Nome do evento
data	Dados do evento (varia por tipo)
timestamp	Data/hora do evento (ISO8601)
attempt	Número da tentativa (0 = primeira)
webhook_token	Token ú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

Você recebe este evento 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

{
  "event": "MESSAGE_SENT",
  "data": {
    "message": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "content": "Olá, como posso ajudar?",
      "type": "text",
      "file": null,
      "direction": "outgoing",
      "visibility": "client",
      "created_at": "2024-12-18T13:55:00.000000Z"
    },
    "chat": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "status": "attending",
      "channel": {
        "id": "01hxyz123abc456def789ghjkm",
        "name": "WhatsApp Atendimento",
        "type": "whatsapp_unofficial"
      },
      "is_open": true,
      "unread_count": 0
    },
    "user": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "name": "João Silva",
      "email": "joao.silva@exemplo.com.br",
      "avatar": "https://exemplo.com/avatars/usr.jpg"
    },
    "contact": {
      "phone": "5511999999999",
      "name": "João Silva",
      "avatar": null,
      "blocked": false,
      "tags": [
        {
          "id": "01k8l9m0n1o2p3q4r5s6t7u8v9w",
          "name": "VIP",
          "color": "#FF5733"
        }
      ]
    }
  },
  "timestamp": "2024-12-18T13:55:00+00:00",
  "attempt": 0,
  "webhook_token": "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

{
  "event": "MESSAGE_RECEIVED",
  "data": {
    "message": {
      "id": "01hxyz123abc456def789ghjkm",
      "content": "Preciso de ajuda com meu pedido",
      "type": "text",
      "file": null,
      "direction": "incoming",
      "visibility": "client",
      "created_at": "2024-12-18T13:56:00.000000Z"
    },
    "chat": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "status": "waiting",
      "channel": {
        "id": "01hxyz123abc456def789ghjkm",
        "name": "WhatsApp Atendimento",
        "type": "whatsapp_unofficial"
      },
      "is_open": true,
      "unread_count": 1
    },
    "user": null,
    "contact": {
      "phone": "5511999999999",
      "name": "João Silva",
      "avatar": null,
      "blocked": false,
      "tags": []
    }
  },
  "timestamp": "2024-12-18T13:56:00+00:00",
  "attempt": 0,
  "webhook_token": "whk_675c1a2b4e5f6"
}

Mensagem com Arquivo

Exemplo de mensagem enviada com imagem:

{
  "event": "MESSAGE_SENT",
  "data": {
    "message": {
      "id": "01j7m8n9p0q1r2s3t4u5v6w7x",
      "content": "https://exemplo.com/produto.jpg",
      "type": "image",
      "file": {
        "id": "01k8l9m0n1o2p3q4r5s6t7u8v9w",
        "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": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "status": "attending",
      "channel": {
        "id": "01hxyz123abc456def789ghjkm",
        "name": "WhatsApp Vendas",
        "type": "whatsapp_unofficial"
      }
    },
    "user": {
      "id": "01j7m8n9p0q1r2s3t4u5v6w7x",
      "name": "João Silva",
      "email": "joao.silva@exemplo.com.br"
    },
    "contact": {
      "phone": "5511999999999",
      "name": "João Silva"
    }
  },
  "timestamp": "2024-12-18T13:57:00+00:00",
  "attempt": 0,
  "webhook_token": "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

{
  "event": "CHAT_CREATED",
  "data": {
    "chat": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "status": "waiting",
      "channel": {
        "id": "01hxyz123abc456def789ghjkm",
        "name": "WhatsApp Atendimento",
        "type": "whatsapp_unofficial"
      },
      "is_open": true,
      "unread_count": 0,
      "created_at": "2024-12-18T13:57:00.000000Z"
    },
    "contact": {
      "phone": "5511999999999",
      "name": "João Silva",
      "avatar": null,
      "blocked": false
    }
  },
  "timestamp": "2024-12-18T13:57:00+00:00",
  "attempt": 0,
  "webhook_token": "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

{
  "event": "CHAT_ENDED",
  "data": {
    "chat": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "status": "finalized",
      "channel": {
        "id": "01hxyz123abc456def789ghjkm",
        "name": "WhatsApp Atendimento",
        "type": "whatsapp_unofficial"
      },
      "is_open": false,
      "unread_count": 0,
      "ended_at": "2024-12-18T14:30:00.000000Z"
    },
    "contact": {
      "phone": "5511999999999",
      "name": "João Silva",
      "avatar": null,
      "blocked": false
    }
  },
  "timestamp": "2024-12-18T14:30:00+00:00",
  "attempt": 0,
  "webhook_token": "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

{
  "event": "CHAT_TRANSFERRED",
  "data": {
    "chat": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "status": "waiting",
      "is_open": true,
      "unread_count": 0,
      "transferred_at": "2024-12-18T14:15:00.000000Z"
    },
    "contact": {
      "phone": "5511999999999",
      "name": "João Silva"
    },
    "from_channel": {
      "id": "01hxyz123abc456def789ghjkm",
      "name": "WhatsApp Vendas",
      "type": "whatsapp_unofficial"
    },
    "to_channel": {
      "id": "01k8l9m0n1o2p3q4r5s6t7u8v9w",
      "name": "WhatsApp Suporte",
      "type": "evolution"
    },
    "to_user": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "name": "João Silva",
      "email": "joao.silva@exemplo.com.br"
    }
  },
  "timestamp": "2024-12-18T14:15:00+00:00",
  "attempt": 0,
  "webhook_token": "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

{
  "event": "CHANNEL_CONNECTED",
  "data": {
    "channel": {
      "id": "01hxyz123abc456def789ghjkm",
      "name": "WhatsApp Atendimento",
      "type": "whatsapp_unofficial",
      "status": "connected",
      "phone": "5511999999999",
      "connected_at": "2024-12-18T14:05:00.000000Z"
    }
  },
  "timestamp": "2024-12-18T14:05:00+00:00",
  "attempt": 0,
  "webhook_token": "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

{
  "event": "CHANNEL_DISCONNECTED",
  "data": {
    "channel": {
      "id": "01hxyz123abc456def789ghjkm",
      "name": "WhatsApp Atendimento",
      "type": "whatsapp_unofficial",
      "status": "disconnected",
      "phone": "5511999999999",
      "disconnected_at": "2024-12-18T16:30:00.000000Z"
    }
  },
  "timestamp": "2024-12-18T16:30:00+00:00",
  "attempt": 0,
  "webhook_token": "whk_675c1a34dm3n5"
}

Estrutura dos Campos

Os identificadores (id) nos objetos retornados seguem o formato ULID (ex.: 01arz3ndektsv4rrffq69g5fav).

message

Campo	Tipo	Descrição
id	string	ID da mensagem (ULID)
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
id	string	ID do chat (ULID)
status	string	Status: `waiting`, `attending`, `finalized`
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	string	ID do usuário (ULID)
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	string	ID do arquivo (ULID)
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:

Abra o site e copie a URL única que ele gera
Cole essa URL no Tinko (em Configurações → Webhooks)
Faça algumas ações no painel do Tinko (enviar mensagem, abrir chat etc.)
Os payloads aparecem em tempo real no gohook

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_token para rastreamento e deduplicação
Trate campos null adequadamente
Para mensagens com arquivo, use file.url para download
Escolha só os eventos que você realmente usa
Use múltiplos webhooks para diferentes finalidades