> ## Documentation Index
> Fetch the complete documentation index at: https://docs-hub-campaign.convertt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /external/campaigns/dispatch

> Dispara uma campanha RCS para até 2.000 destinatários

## Autenticação

Requer OAuth Bearer token com scope `campaigns:dispatch`.

```
Authorization: Bearer {access_token}
```

## Request Body

<ParamField body="campaignId" type="string" required>
  UUID da campanha. Controlado pelo cliente — será usado como identificador interno.
</ParamField>

<ParamField body="name" type="string" required>
  Nome da campanha. Deve ser único por tenant.
</ParamField>

<ParamField body="templateId" type="string" required>
  UUID do template RCS a ser usado. Deve pertencer ao mesmo tenant.
</ParamField>

<ParamField body="messages" type="array" required>
  Array de mensagens (máximo 2.000 por chamada).

  <Expandable title="Propriedades de cada mensagem">
    <ParamField body="phone" type="string" required>
      Número do destinatário. Formatos aceitos: `5511999999999`, `11999999999`, `+5511999999999`.
    </ParamField>

    <ParamField body="uid" type="string" required>
      Identificador único da mensagem no sistema do cliente. Retornado nos webhooks para correlação.
    </ParamField>

    <ParamField body="vars" type="object">
      Variáveis dinâmicas do template. Ex: `{"nome": "João", "produto": "TV"}`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="batch" type="string">
  Identificador do lote. Obrigatório quando `campaignId` já existe (batch incremental); deve ser único por campanha.
</ParamField>

<ParamField body="schedule" type="string">
  Data/hora ISO 8601 para agendamento (fuso horário America/Sao\_Paulo). Deve ser no mínimo 5 minutos no futuro.
</ParamField>

## Resposta de Sucesso (202 Accepted)

```json theme={null}
{
  "campaignId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sending",
  "accepted": 1950,
  "rejected": 50,
  "feedback": {
    "invalidPhones": [
      { "phone": "123", "reason": "Número inválido: 123..." }
    ],
    "errorFileUrl": "https://s3.../errors.csv"
  }
}
```

<ResponseField name="campaignId" type="string">UUID da campanha criada.</ResponseField>
<ResponseField name="status" type="string">`sending` para envio imediato, `scheduled` para agendamento.</ResponseField>
<ResponseField name="accepted" type="number">Quantidade de mensagens aceitas para envio.</ResponseField>
<ResponseField name="rejected" type="number">Quantidade de mensagens rejeitadas (telefones inválidos).</ResponseField>

<ResponseField name="feedback" type="object">
  Detalhes dos erros. Se houver mais de 5 telefones inválidos, um arquivo CSV com os erros é gerado e retornado em `errorFileUrl`.
</ResponseField>

## Validações

| Validação                                          | Erro            |
| -------------------------------------------------- | --------------- |
| `campaignId` não é UUID                            | 400 Bad Request |
| `templateId` não existe                            | 404 Not Found   |
| Template pertence a outro tenant                   | 403 Forbidden   |
| Nome de campanha duplicado                         | 409 Conflict    |
| `messages` vazio ou > 2000                         | 400 Bad Request |
| `uid` ausente em alguma mensagem                   | 400 Bad Request |
| Variáveis do template ausentes                     | 400 Bad Request |
| `schedule` \< 5 minutos no futuro                  | 400 Bad Request |
| `batch` ausente em disparo para campanha existente | 400 Bad Request |
| `batch` já utilizado nesta campanha                | 409 Conflict    |
| Número já despachado em batch anterior             | 409 Conflict    |
| `campaignId` já existe com nome diferente          | 409 Conflict    |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api-hub-campaign.convertt.ai/api/v1/external/campaigns/dispatch \
    -H "Authorization: Bearer eyJhbG..." \
    -H "Content-Type: application/json" \
    -d '{
      "campaignId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Promoção Black Friday 2025",
      "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "messages": [
        {
          "phone": "5511999999999",
          "uid": "user-001",
          "vars": { "nome": "João", "desconto": "30%" }
        },
        {
          "phone": "5521988888888",
          "uid": "user-002",
          "vars": { "nome": "Maria", "desconto": "25%" }
        }
      ],
      "batch": "batch-001"
    }'
  ```
</RequestExample>