Publicações de Status

Evento: status_posts · Transporte: POST para o seu receptor

Receba as publicações de Status (status@broadcast) dos seus contatos e os Status de grupo em tempo real, em evento separado de messages.

Inscrição explícita

O evento só é entregue a quem inclui status_posts pelo nome em events, no webhook da instância, no webhook global ou no SSE. Lista vazia ou All não incluem status_posts, para não enviar os Status de todos os contatos a quem não pediu. Enquanto ninguém estiver inscrito, a instância descarta os Status recebidos; eles não são entregues depois.

Diferenças em relação a messages

message.chatid é status@broadcast e message.isStatus é true. No Status de grupo, publicado por qualquer membro (inclusive a própria conta), message.chatid é o JID do grupo (@g.us) e message.isGroup é true. O autor está em message.sender, com sender_pn, sender_lid e senderName quando disponíveis. Publicações da própria conta chegam com fromMe: true.

Enquanto há inscritos, cada publicação é gravada antes do webhook, com chatid: status@broadcast: a mídia pode ser baixada por POST /message/download assim que o evento chega, e a publicação aparece em POST /message/find (filtrando por chatid: status@broadcast ou sem chatid). Ela sai na limpeza normal de mensagens. O Status de grupo fica na conversa do grupo, com messageType: GroupStatusMessage e o texto em text, e também sai em 24 horas (o de campanha do /sender fica com a campanha): liste com POST /message/find e messageType: GroupStatusMessage. A publicação não cria chat nem contador de não lidas e não dispara chatbot, fluxos ou Chatwoot. Respostas a um Status continuam chegando pela conversa individual, no evento messages.

Limites

Só publicações recebidas enquanto a instância está conectada. Edições, exclusões, reações e visualizações de Status não geram este evento. Os filtros fromMeYes, fromMeNo, wasSentByApi e wasNotSentByApi de excludeMessages também valem aqui; isGroupYes e isGroupNo não. Para separar os Status de grupo dos de contatos, use message.isGroup.

Habilitar este evento

Adicione status_posts à 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": [
    "status_posts"
  ]
}

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.
`message`	object	Publicação de Status normalizada. Campos disponíveis variam conforme o tipo.
`message.id`	string	Identificador retornado pelo sistema (`owner:messageid`); preserve como string.
`message.messageid`	string	ID da publicação no WhatsApp.
`message.chatid`	string	`status@broadcast` nos Status de contatos; o JID do grupo (`@g.us`) no Status de grupo.
`message.sender`	string	JID do autor da publicação.
`message.senderName`	string	Nome disponível do autor.
`message.sender_pn`	string	Número do autor (`@s.whatsapp.net`), quando conhecido.
`message.sender_lid`	string	LID do autor, quando conhecido.
`message.isStatus`	boolean	Sempre `true` neste evento.
`message.isGroup`	boolean	`true` no Status de grupo (`chatid` do grupo); `false` nos Status de contatos.
`message.fromMe`	boolean	Publicação feita pela própria conta conectada.
`message.wasSentByApi`	boolean	Publicação enviada pela API.
`message.messageType`	string	Tipo da mensagem do WhatsApp, por exemplo `ExtendedTextMessage`, `ImageMessage` ou `VideoMessage`.
`message.mediaType`	string	Tipo de mídia informado pelo WhatsApp; vazio em texto.
`message.type`	string	Categoria normalizada (`text` ou `media`).
`message.text`	string	Texto ou legenda disponível.
`message.content`	variável	Conteúdo específico do tipo de mensagem, com as referências de mídia usadas por `POST /message/download`; não possui um formato único.
`message.source`	string	Plataforma de origem inferida pelo ID.
`message.messageTimestamp`	integer	Timestamp da publicação em milissegundos Unix.
`message.owner`	string	Conta conectada que recebeu a publicação.

Exemplos de entrega

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

Status de texto

{
  "EventType": "status_posts",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "message": {
    "id": "5511999999999:3EB0STATUS0001",
    "messageid": "3EB0STATUS0001",
    "chatid": "status@broadcast",
    "sender": "5511988887777@s.whatsapp.net",
    "senderName": "Maria",
    "sender_pn": "5511988887777@s.whatsapp.net",
    "sender_lid": "123456789012345@lid",
    "isStatus": true,
    "isGroup": false,
    "fromMe": false,
    "wasSentByApi": false,
    "messageType": "ExtendedTextMessage",
    "mediaType": "",
    "type": "text",
    "text": "Promoção só hoje!",
    "messageTimestamp": 1788868800000,
    "owner": "5511999999999"
  }
}

Status de imagem com legenda

{
  "EventType": "status_posts",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "message": {
    "id": "5511999999999:3EB0STATUS0002",
    "messageid": "3EB0STATUS0002",
    "chatid": "status@broadcast",
    "sender": "5511988887777@s.whatsapp.net",
    "senderName": "Maria",
    "sender_pn": "5511988887777@s.whatsapp.net",
    "sender_lid": "123456789012345@lid",
    "isStatus": true,
    "isGroup": false,
    "fromMe": false,
    "wasSentByApi": false,
    "messageType": "ImageMessage",
    "mediaType": "image",
    "type": "media",
    "text": "Novidades da semana",
    "content": {
      "caption": "Novidades da semana",
      "mimetype": "image/jpeg"
    },
    "messageTimestamp": 1788868860000,
    "owner": "5511999999999"
  }
}

Status de grupo publicado por um membro

{
  "EventType": "status_posts",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "message": {
    "id": "5511999999999:3EB0STATUS0003",
    "messageid": "3EB0STATUS0003",
    "chatid": "120363012345678901@g.us",
    "sender": "123456789012345@lid",
    "senderName": "Maria",
    "sender_pn": "5511988887777@s.whatsapp.net",
    "sender_lid": "123456789012345@lid",
    "isStatus": true,
    "isGroup": true,
    "fromMe": false,
    "wasSentByApi": false,
    "messageType": "ExtendedTextMessage",
    "mediaType": "",
    "type": "text",
    "text": "Reunião do grupo amanhã às 19h",
    "messageTimestamp": 1788868920000,
    "owner": "5511999999999"
  }
}

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.