Processamento de campanhas

Evento: sender · Transporte: POST para o seu receptor

Acompanhe início e conclusão do processamento de uma pasta de campanha.

Estados e contadores

`status`	Conteúdo principal
`sending`	`folderID`, `folderInfo`, `messageCount`, `scheduledFor`, `startedAt`
`done`	`folderID`, `folderInfo`, `successCount`, `failedCount`, `completedAt`

Correlacione pelo folderID dentro da instância. Os timestamps de início/conclusão usam milissegundos Unix. O término do processamento e os contadores da campanha não equivalem à leitura de todas as mensagens pelos destinatários; para isso, acompanhe os eventos de mensagens correspondentes.

A notificação de início ocorre na transição de scheduled para sending; não espere um novo evento de início a cada retomada interna.

Habilitar este evento

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

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.
`folderID`	string	ID da pasta de campanha.
`folderInfo`	string	Informação descritiva da pasta.
`status`	string	Fase notificada do processamento.
`messageCount`	integer	Quantidade no início do processamento.
`scheduledFor`	integer	Agendamento informado pela pasta.
`startedAt`	integer	Início em milissegundos Unix.
`successCount`	integer	Contagem de sucesso registrada pelo processamento.
`failedCount`	integer	Contagem de falhas registrada pelo processamento.
`completedAt`	integer	Conclusão em milissegundos Unix.

Exemplos de entrega

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

Início de processamento

{
  "EventType": "sender",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "folderID": "r0123456789abcd",
  "folderInfo": "Campanha de exemplo",
  "status": "sending",
  "messageCount": 20,
  "scheduledFor": 1788868800000,
  "startedAt": 1788868800000
}

Processamento concluído

{
  "EventType": "sender",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "folderID": "r0123456789abcd",
  "folderInfo": "Campanha de exemplo",
  "status": "done",
  "successCount": 19,
  "failedCount": 1,
  "completedAt": 1788868860000
}

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.