# 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.

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

Envie essa configuração para [POST /webhook](/reference/updateWebhook.md), 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

```json
{
  "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

```json
{
  "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](/docs/integrations-webhooks#diagnostico) e implemente a reconciliação necessária. Eventos repetidos ou fora de ordem ainda precisam ser tolerados pelo receptor.

## Referências

- [Introdução, configuração e catálogo](/docs/integrations-webhooks)
- [Autenticação](/docs/authentication)
- [Contrato OpenAPI completo](/openapi-bundled.json)