Configuração de Webhook

Webhook Personalizado

Configure um webhook para receber notificações de mensagens recebidas. Se configurado, as mensagens serão enviadas para esta URL. O webhook deve ser um endpoint POST que aceite JSON.

Modelo de Payload e Explicação dos Campos

Este é o formato enviado para seu webhook quando uma mensagem é recebida.

{
  "origin": {
    "phone": "351912582196",
    "code": "351912582196@c.us",
    "name": "Karine Lopes",
    "photoUrl": "https://cdn.exemplo.com/avatars/karine.jpg",
    "isGroup": true,
    "isNewsletter": false,
    "participantPhone": "103341577240798",
    "contact": {
      "displayName": "Karine Lopes",
      "vCard": "BEGIN:VCARD\\nVERSION:3.0\\nN:Lopes;Karine;;;\\nTEL;TYPE=CELL:351912582196\\nEND:VCARD",
      "phones": ["351912582196"]
    }
  },
  "destination": {
    "phone": "351910553378",
    "code": "351910553378@c.us",
    "name": "Portugal x Brasil",
    "chatId": "120363426688047287@g.us",
    "chatType": "group",
    "participantsCount": 42,
    "isBotAdmin": true,
    "broadcast": false,
    "deviceType": "ios",
    "isStatus": false,
    "isForwarded": true,
    "forwardingScore": 1
  },
  "message": {
    "id": "false_120363426688047287@g.us_3AA5209D8832F09747F1_103341577240798@lid",
    "type": "image",
    "status": "RECEIVED",
    "ack": 3,
    "fromMe": false,
    "hasMedia": true,
    "hasQuotedMsg": true,
    "hasReaction": false,
    "durationSeconds": null,
    "referenceMessageId": "false_120363426688047287@g.us_3AC5EB67C4D73E52D6A4_21423313653805@lid",
    "quoted": { "id": "false_...@lid", "body": "Mensagem citada", "fromCode": "351912582196@c.us" },
    "mentions": ["351912582196@c.us","5511990000000@c.us"],
    "text": { "body": "Veja a imagem" },
    "links": ["https://exemplo.com"],
    "vCards": [],
    "media": {
      "type": "image",
      "image": {
        "caption": "Imagem do evento",
        "mimeType": "image/jpeg",
        "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABA...",
        "fileName": "evento.jpg",
        "fileSize": 24567,
        "extension": "jpg"
      },
      "audio": null,
      "video": null,
      "document": null,
      "location": null,
      "sticker": null
    },
    "meta": {
      "type": "ReceivedCallback",
      "requestMethod": "POST",
      "isStatusReply": false,
      "waitingMessage": false,
      "isEdit": false,
      "timestamp": 1773840846,
      "momment": 1773840846000,
      "messageExpirationSeconds": 86400,
      "expiresAt": "2026-03-25T00:00:00.000Z",
      "callId": "call_123"
    },
    "extra": {
      "hydratedTemplate": "template_abc",
      "notification": "group_update",
      "notificationParameters": { "event": "forwarded" },
      "externalAdReply": "https://exemplo.com/ad",
      "statusImage": "https://cdn.exemplo.com/status/123.jpg",
      "code": "XYZ"
    }
  }
}
                

Respostas de Menu (send-list)

Quando o usuário escolhe uma opção do menu, o WhatsApp envia uma resposta interativa. O sistema encaminha no webhook com o rowId selecionado em message.text.body e detalhes em message.extra.interactive.

{
  "origin": { "phone": "5511999999999", "isGroup": false },
  "destination": { "phone": "5511888888888", "chatType": "private" },
  "message": {
    "type": "listResponseMessage",
    "text": { "body": "opt_2" },
    "extra": {
      "interactive": { "kind": "list", "selectedRowId": "opt_2", "title": "Opção 2", "description": "Descrição 2" }
    }
  }
}
                

Campos Principais

origin

phone: telefone do remetente (normalizado)
code: identificador no WhatsApp (ex.: 5511...@c.us)
name: nome exibido do contato
photoUrl: URL da foto do perfil (quando disponível)
isGroup: indica se a mensagem vem de um grupo
isNewsletter: indica se é canal/newsletter
participantPhone: telefone do autor no grupo (quando aplicável)
contact: detalhes do contato (displayName, vCard, phones)

destination

phone: telefone da sua conta conectada
code: identificador da conta/chat destino
name: nome do chat/grupo
chatId: id do chat (grupos terminam com @g.us)
chatType: private, group ou newsletter
participantsCount: total de participantes (se grupo)
isBotAdmin: bot é administrador do grupo
deviceType: origem do dispositivo do remetente

message

type: tipo da mensagem (chat, image, audio, etc.)
status/ack: status de entrega e código
text.body: conteúdo textual
media: objeto com type e conteúdo específico
quoted: dados da mensagem citada (se houver)
mentions: lista de usuários mencionados
meta: metadados (timestamp, expiração, etc.)
extra: dados adicionais específicos do WhatsApp
extra.interactive: quando aplicável, contém dados de respostas interativas (ex.: lista/menus)