> ## Documentation Index
> Fetch the complete documentation index at: https://ajuda.pandazap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Envie Mensagens em Massa para Listas de Contatos em uma Única Chamada de API

> Dispare textos ou templates WABA para grandes listas de contatos, com atrasos configuráveis e substituição de variáveis por destinatário usando a API do PanÐá Zap.

Os endpoints de envio em massa permitem disparar mensagens para grandes listas de contatos em uma única chamada de API. Você pode enviar o mesmo texto para todos os destinatários, personalizar cada mensagem usando variáveis por linha a partir de uma entrada CSV, disparar envios individuais rastreados, ou gerenciar os jobs de disparo resultantes — tudo através da API externa do PanÐá Zap.

## Visão Geral

Os endpoints de envio em massa permitem disparar mensagens para grandes listas de contatos em uma única chamada de API. Você pode enviar o mesmo texto para todos os destinatários, personalizar mensagens usando variáveis por linha a partir de uma entrada CSV, ou disparar envios individuais que são rastreados como parte de uma campanha de disparo.

**URL Base**

```text theme={null}
https://{BaseUrl}/v2/api/external/{ApiID}/
```

**Autenticação**

```text theme={null}
Authorization: Bearer {BearerToken}
```

<Warning>
  Sempre defina um atraso entre os envios. O mínimo recomendado é `min: 5` / `max: 15` segundos. Enviar mensagens muito rapidamente em sequência viola as políticas do WhatsApp e aumenta significativamente o risco de seu número ser sinalizado ou banido. Nunca defina `min` e `max` como `0` ao mesmo tempo.
</Warning>

***

## Endpoints

### BulkSendMessage — Enviar para um Array de Números

Envie a mesma mensagem de texto para todos os números da lista fornecida.

```text theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/bulkSendMessage
```

```json Request theme={null}
{
  "whatsappId": 12,
  "arrayNumbers": [
    "5511999990001",
    "5511999990002",
    "5511999990003"
  ],
  "message": "Hello! We have a special offer for you.",
  "min": 5,
  "max": 15
}
```

<ParamField body="whatsappId" type="integer" required>
  O ID do canal (conexão do WhatsApp) do qual enviar.
</ParamField>

<ParamField body="arrayNumbers" type="array" required>
  Array de números de telefone para enviar. Inclua código do país e DDD — por exemplo, `"5511999990001"`.
</ParamField>

<ParamField body="message" type="string" required>
  O conteúdo de texto a ser enviado para todos os destinatários da lista.
</ParamField>

<ParamField body="min" type="integer" required>
  Atraso mínimo em segundos entre cada envio. Mínimo recomendado: `5`.
</ParamField>

<ParamField body="max" type="integer" required>
  Atraso máximo em segundos entre cada envio. Um valor aleatório entre `min` e `max` é escolhido para cada destinatário. Mínimo recomendado: `15`.
</ParamField>

***

### BulkSendMessageWithVariable — Mensagens Personalizadas via CSV

Envie uma mensagem personalizada para cada destinatário substituindo variáveis a partir de uma string formatada em CSV.

```text theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/bulkSendMessageWithVariable
```

```json Request theme={null}
{
  "whatsappId": 12,
  "message": "Hi {{var1}}, your invoice {{var2}} is due tomorrow.",
  "dataInput": "5511999990001,Maria,INV-001\n5511999990002,João,INV-002\n5511999990003,Ana,INV-003",
  "min": 5,
  "max": 15
}
```

<ParamField body="whatsappId" type="integer" required>
  O ID do canal do qual enviar.
</ParamField>

<ParamField body="message" type="string" required>
  Modelo de mensagem usando `{{var1}}`, `{{var2}}`, etc. como marcadores. Cada marcador é substituído pelo valor da coluna correspondente em `dataInput` para aquele destinatário.
</ParamField>

<ParamField body="dataInput" type="string" required>
  String formatada em CSV onde cada linha representa um destinatário. Formato por linha: `number,var1,var2,...`. Use `\n` para separar as linhas. Envolva valores de campo que contenham vírgulas em aspas duplas.
</ParamField>

<ParamField body="min" type="integer" required>
  Atraso mínimo em segundos entre os envios.
</ParamField>

<ParamField body="max" type="integer" required>
  Atraso máximo em segundos entre os envios.
</ParamField>

**Exemplo — como o `dataInput` mapeia para `{{var1}}` e `{{var2}}`:**

| Linha | number          | `{{var1}}` | `{{var2}}` |
| ----- | --------------- | ---------- | ---------- |
| 1     | `5511999990001` | `Maria`    | `INV-001`  |
| 2     | `5511999990002` | `João`     | `INV-002`  |
| 3     | `5511999990003` | `Ana`      | `INV-003`  |

***

### BulkFastMessage — Envio em Massa com Atraso Fixo

Uma variante de envio em massa de maior throughput que usa um atraso fixo em vez de um intervalo aleatório. Adequada para cenários em que um ritmo constante é preferível a um espaçamento aleatorizado.

```text theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/bulkFastMessage
```

```json Request theme={null}
{
  "whatsappId": 12,
  "whatsappType": "baileys",
  "arrayNumbers": [
    "5511999990001",
    "5511999990002"
  ],
  "message": "Important update from our team.",
  "min": 5,
  "max": 5
}
```

<ParamField body="whatsappId" type="integer" required>
  O ID do canal do qual enviar.
</ParamField>

<ParamField body="whatsappType" type="string" required>
  O tipo da conexão do WhatsApp — por exemplo, `"baileys"`.
</ParamField>

<ParamField body="arrayNumbers" type="array" required>
  Array de números de telefone para enviar.
</ParamField>

<ParamField body="message" type="string" required>
  O conteúdo de texto a ser enviado para todos os destinatários.
</ParamField>

<ParamField body="min" type="integer" required>
  Defina com o mesmo valor de `max` para usar um atraso fixo. Valor mínimo recomendado: `5`.
</ParamField>

<ParamField body="max" type="integer" required>
  Defina com o mesmo valor de `min` para um atraso fixo.
</ParamField>

***

### BulkIndividual — Envio Único com Rastreamento de Disparo

Envie uma mensagem para um contato com um `externalKey` para rastreamento via webhook. Útil quando você precisa disparar envios a partir de automações externas e correlacionar eventos de entrega de volta ao seu sistema.

```text theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/bulkIndividual
```

```json Request theme={null}
{
  "whatsappId": 12,
  "number": "5511999990001",
  "message": "Your order has been shipped.",
  "externalKey": "order-shipped-78901"
}
```

<ParamField body="whatsappId" type="integer" required>
  O ID do canal do qual enviar.
</ParamField>

<ParamField body="number" type="string" required>
  Número de telefone do destinatário, com código do país e DDD.
</ParamField>

<ParamField body="message" type="string" required>
  O conteúdo de texto da mensagem.
</ParamField>

<ParamField body="externalKey" type="string" required>
  Chave única gerada pelo seu sistema. Usada para correlacionar o envio com seu callback de webhook e evitar entrega duplicada em caso de nova tentativa.
</ParamField>

***

## Verificação de Ticket Ativo

Quando a configuração do tenant **"Verificar conversa em outros canais"** está ativada, qualquer contato que já tenha um ticket aberto ou pendente em **qualquer canal** é automaticamente ignorado durante o disparo em massa. A resposta inclui um resumo dos contatos ignorados:

```json theme={null}
{
  "success": true,
  "data": {
    "sent": 2,
    "skipped": 1,
    "skippedNumbers": ["5511999990003"]
  }
}
```

<Note>
  Para ignorar a verificação de ticket ativo em uma chamada específica de envio em massa, inclua `"skipActiveTicketCheck": true` no corpo da sua requisição. Isso envia para todos os contatos da lista, independentemente de terem ou não uma conversa em aberto.
</Note>

***

## Gerenciando Disparos em Massa

### Listar Todos os Disparos

Obtenha uma lista paginada de todos os jobs de disparo em massa da sua API.

```text theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/bulkDispatch/list?page=1&limit=20
```

| Parâmetro de Consulta | Tipo    | Descrição                                        |
| --------------------- | ------- | ------------------------------------------------ |
| `page`                | integer | Número da página a ser retornada. Começa em `1`. |
| `limit`               | integer | Número de disparos a retornar por página.        |

***

### Obter Detalhes do Disparo

Obtenha o status completo e as estatísticas de um disparo específico.

```text theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/bulkDispatch/show/{dispatchId}
```

| Parâmetro de Caminho | Tipo    | Descrição                     |
| -------------------- | ------- | ----------------------------- |
| `dispatchId`         | integer | O ID do disparo a ser obtido. |

***

### Cancelar um Disparo

Interrompa um disparo em execução ou na fila antes que ele seja concluído.

```text theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/bulkDispatch/update/{dispatchId}
```

```json Request theme={null}
{
  "status": "cancelled",
  "cancellationReason": "Campaign paused by user"
}
```

| Parâmetro de Caminho | Tipo    | Descrição                        |
| -------------------- | ------- | -------------------------------- |
| `dispatchId`         | integer | O ID do disparo a ser cancelado. |

<ParamField body="status" type="string" required>
  Defina como `"cancelled"` para interromper o disparo.
</ParamField>

<ParamField body="cancellationReason" type="string">
  Motivo opcional e legível para o cancelamento. Armazenado no registro do disparo para fins de auditoria.
</ParamField>