Mensagens de canais

Evento: newsletter_messages · Transporte: POST para o seu receptor

Receba mensagens de canais/newsletters disponíveis para a sessão.

Diferenças em relação a messages

O payload inclui newsletter e message. Preserve o JID terminado em @newsletter. O ID normalizado da mensagem combina informações do ID e do identificador de servidor; não reconstrua esse valor por conta própria.

Use message.isNewsletter, newsletterServerId e os identificadores retornados para reconhecer esse fluxo. A API não transforma toda alteração de canal em mensagem: stanzas de protocolo/reações podem ser ignoradas pelo emissor; consulte as rotas específicas de newsletter para atualizar o estado.

O evento não garante histórico completo nem substitui a consulta de mensagens recentes do canal.

Habilitar este evento

Adicione newsletter_messages à lista events do webhook da instância. Preserve os outros eventos de que sua integração precisa.

{
  "enabled": true,
  "url": "https://seu-sistema.example/hooks/whatsapp",
  "events": [
    "newsletter_messages"
  ]
}

Envie essa configuração para POST /webhook, usando o header token. O JSON acima configura a assinatura; os exemplos de entrega abaixo são o que seu servidor recebe.

Campos do payload

O envelope comum vem na raiz. Campos condicionais podem estar ausentes ou nulos conforme o evento; não use a tabela como obrigação de presença de todos os campos.

Campo	Tipo	Significado
`EventType`	string	Obrigatório. Tipo de evento, por exemplo connection ou messages.
`owner`	string	Obrigatório. Consulte o objeto ou exemplo correspondente.
`token`	string	Obrigatório. Token da instância; dado sensível.
`BaseUrl`	string	Obrigatório. Consulte o objeto ou exemplo correspondente.
`instanceName`	string	Consulte o objeto ou exemplo correspondente.
`newsletter`	object	Identificação do canal.
`newsletter.jid`	string	JID do canal, quando incluído na projeção.
`newsletter.id`	string	Parte de usuário do JID do canal.
`newsletter.chatid`	string	JID completo do canal.
`newsletter.server`	string	Domínio do identificador, newsletter.
`message`	object	Mensagem normalizada. Campos disponíveis variam conforme o tipo e a origem.
`message.id`	string	Identificador retornado pelo sistema; preserve como string.
`message.messageid`	string	ID da mensagem no WhatsApp.
`message.chatid`	string	JID do contato, grupo ou canal.
`message.sender`	string	JID do remetente.
`message.senderName`	string	Nome disponível do remetente.
`message.fromMe`	boolean	Mensagem enviada pela conta conectada.
`message.wasSentByApi`	boolean	Origem na API quando esse campo estiver presente na mensagem.
`message.isGroup`	boolean	Identifica conversa de grupo.
`message.messageType`	string	Tipo de mensagem normalizado.
`message.text`	string	Texto ou legenda disponível.
`message.messageTimestamp`	integer	Timestamp da mensagem em milissegundos Unix.
`message.content`	variável	Conteúdo específico do tipo de mensagem; não possui um formato único.
`message.status`	string	Estado disponível da mensagem; pode estar vazio.
`message.isNewsletter`	boolean	Indica mensagem de canal.
`message.newsletterServerId`	integer	ID de servidor da mensagem de canal.
`message.newsletterMeta`	variável	Metadados específicos do canal, quando disponíveis.

Exemplos de entrega

Exemplos ilustrativos com identificadores fictícios. O conteúdo específico e os campos opcionais variam.

Mensagem de canal

{
  "EventType": "newsletter_messages",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "newsletter": {
    "jid": "120363000000000001@newsletter",
    "id": "120363000000000001",
    "chatid": "120363000000000001@newsletter",
    "server": "newsletter"
  },
  "message": {
    "id": "MSG_CANAL:42",
    "messageid": "MSG_CANAL",
    "chatid": "120363000000000001@newsletter",
    "isNewsletter": true,
    "isGroup": false,
    "fromMe": false,
    "messageType": "Conversation",
    "text": "Atualização do canal",
    "messageTimestamp": 1788868800000,
    "newsletterServerId": 42
  }
}

Responder ao webhook

Seu receptor deve aceitar o POST JSON e devolver uma resposta 2xx rapidamente, após validar e registrar o recebimento. O corpo da resposta não é um comando para a API. Processe trabalho demorado separadamente.

O worker não repete automaticamente uma entrega HTTP malsucedida. Consulte diagnóstico de webhooks e implemente a reconciliação necessária. Eventos repetidos ou fora de ordem ainda precisam ser tolerados pelo receptor.