# API de Transmissões

Uma **transmissão** é um envio de saída: um público, uma mensagem de abertura, um canal e um agendamento. Opcionalmente, ela também nomeia o Agente de IA que lida com as respostas recebidas. A API de Transmissões permite que você crie, precifique, lance e monitore esses envios a partir do seu próprio código, em vez do painel. Para o produto em si, consulte o [guia de Transmissões](../broadcasts/broadcasts.md).

- **URL Base** — `https://api.youraiconnector.com/v1`
- **Autenticação** — sua chave de API (veja [Autenticação](authentication.md))
- **Erros e paginação** — veja [Erros e Paginação](errors-and-pagination.md)

Todos os exemplos abaixo mostram a forma de consulta `?apiKey=` em cURL e o cabeçalho `X-API-Key` em JavaScript e Python — ambos funcionam em todos os endpoints.

> **No explorador de API.** Cada endpoint nesta página está na especificação OpenAPI publicada, para que você possa navegar pelos seus campos exatos e executar solicitações ao vivo no [explorador de API](reference.md).


---

## Como um envio é montado

Enviar uma transmissão requer quatro chamadas, não uma:

1. **Crie** a transmissão com seu público, canal e agendamento — ela começa como um `Draft`.
2. **Defina a mensagem de abertura.** No WhatsApp Business, isso significa enviar um modelo para aprovação (ou escolher um que você já tenha aprovado). Em qualquer outro canal, é texto simples.
3. **Estime o custo** se você quiser verificar o preço antes de gastar qualquer coisa (opcional).
4. **Lance a transmissão.** O lançamento executa uma verificação completa — público, mensagem, aprovação de modelo, remetente conectado — e inicia o envio ou informa exatamente o que está faltando.

Nada é enviado até que você chame o lançamento.

---

## O objeto de transmissão

```json
{
  "id": "bcd123abc456",
  "name": "June promo",
  "status": "Draft",
  "channel": "whatsapp",
  "agent_id": "agt_789",
  "list_id": "lst_456",
  "list_name": "Newsletter subscribers",
  "total_contacts": 240,
  "send_to_new_list_members": false,
  "whats_app_template": {
    "body": "Hi {{first_name}}, our June offer is live.",
    "status": "approved",
    "sid": "HX0123...",
    "language": "en",
    "category": "marketing",
    "variables": ["first_name"]
  },
  "execution_date": 1781000000000,
  "drip_mode": true,
  "time_critical": false,
  "total_contacts_sent": 0,
  "credits_used": 0,
  "created_at": 1780900000000,
  "last_modified_at": 1780900000000
}
```

**Os carimbos de data/hora retornam como milissegundos da época** (`execution_date`, `created_at`, `last_modified_at`, …), e qualquer referência de contato retorna como uma string de caminho como `contacts/uid_whatsapp_15551234567`.

### Campos que você define

| Campo | Descrição |
|---|---|
| `name` | Como a transmissão é chamada no painel. |
| `channel` | O único canal no qual esta transmissão é enviada: `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `messenger`, `facebook`, `telegram`, `instagram_private`, `line`, `viber`, `imessage`, `email`, `chat_widget`, `custom_channel`. Uma transmissão tem exatamente um canal — para enviar a mesma coisa em outro lugar, [duplique-a em outro canal](#duplicate-a-broadcast). `tiktok` e `skool` são apenas para resposta e nunca podem ser usados para transmissões. |
| `agent_id` | O Agente de IA que responde às mensagens. Deixe como `null` e as respostas irão para a caixa de entrada da sua equipe. |
| `list_id` | A lista de contatos para a qual enviar. É assim que você define o público a partir da API — consulte [Contatos](contacts.md) para criar e preencher listas. |
| `list_name` | Nome de exibição mostrado ao lado da transmissão. Cosmético. |
| `send_to_new_list_members` | `true` mantém a transmissão armada para que qualquer pessoa adicionada à lista posteriormente também receba a mensagem de abertura. |
| `whats_app_template` | A mensagem de abertura. No WhatsApp Business, é um modelo aprovado real; em qualquer outro canal, seu `body` é usado como o texto de abertura simples. Defina-o através dos [endpoints de modelo](#the-opening-message), não manualmente. |
| `opener_media` | Uma imagem ou vídeo enviado com a abertura. Sempre envie o objeto inteiro (ou `null` para removê-lo) — escrever chaves individuais dentro dele será rejeitado. Não suportado em SMS. |
| `execution_date` | Quando enviar. Envie um carimbo de data/hora ISO 8601 ou milissegundos da época. Uma data futura agenda o envio; omita-o (ou use uma data passada) para enviar assim que você lançar. |
| `drip_mode` | `true` espaça o envio em lotes ao longo do tempo, em vez de tudo de uma vez. |
| `time_critical` | `true` desativa o espaçamento automático que entra em vigor acima de 50 contatos — para um público aquecido que precisa da mensagem agora. Isso não aumenta o limite diário de envio do próprio canal. |
| `batch_size` | Quantos contatos por lote ao usar o envio gradual (dripping). |
| `follow_up_config` | A cadeia de acompanhamento para contatos que nunca respondem. |

Qualquer coisa que você enviar como `user_id`, `id`, `status` ou `source_campaign_id` é ignorada na criação e descartada na atualização — o status só muda através dos endpoints de lançamento, pausa e retomada abaixo.

### Campos que a plataforma mantém

`status`, `total_contacts_sent`, `unique_contacts_replied`, `overall_reply_rate`, `credits_used`, `paused_reason`, `completion_summary`, os contadores de lote e `contacts` (os contatos individuais anexados a partir do painel, lidos de volta como strings de caminho). Leia-os, não os escreva.

### Status

| Status | Significado |
|---|---|
| `Draft` | Sendo criado. Nada está agendado. |
| `Pending Approval` | Lançado, mas seu modelo de WhatsApp ainda aguarda uma decisão. Ele começa a enviar automaticamente assim que o modelo for aprovado — você não precisa lançar novamente. |
| `Scheduled` | Lançado com um `execution_date` futuro. |
| `Sending` | Enviando ativamente (uma transmissão armada para novos membros da lista permanece aqui enquanto aguarda por eles). |
| `Paused` | Em espera — por você ou automaticamente por uma verificação de segurança. |
| `Sent` | Concluído. |
| `Failed` | Concluído com mais da metade dos envios falhando. |

---

## Criar uma transmissão

`POST /broadcasts` — cria uma `Draft`.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June promo",
    "channel": "whatsapp",
    "list_id": "lst_456",
    "agent_id": "agt_789",
    "drip_mode": true,
    "execution_date": "2026-06-15T09:00:00.000Z"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "June promo",
    channel: "whatsapp",
    list_id: "lst_456",
    agent_id: "agt_789",
    drip_mode: true,
    execution_date: "2026-06-15T09:00:00.000Z",
  }),
});
const { broadcast_id } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "June promo",
        "channel": "whatsapp",
        "list_id": "lst_456",
        "agent_id": "agt_789",
        "drip_mode": True,
        "execution_date": "2026-06-15T09:00:00.000Z",
    },
)
print(res.json()["broadcast_id"])
```

**Resposta** (`201`)

```json
{ "success": true, "broadcast_id": "bcd123abc456" }
```

---

## Listar transmissões

`GET /broadcasts` — todas as transmissões na conta, da mais recente para a mais antiga.

**Parâmetros de consulta**

| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| `status` | Não | Retorna apenas transmissões em um status, ex.: `Sending`. Combine a grafia exatamente com a [tabela de status](#statuses). |

```bash
curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();
```

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]
```

**Resposta** (`200`)

```json
{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }
```

---

## Obter uma transmissão

`GET /broadcasts/{broadcastId}` — retorna `{ "success": true, "broadcast": { ... } }`. Use-o para verificar um envio em andamento: `total_contacts_sent`, `unique_contacts_replied`, `overall_reply_rate` e `credits_used` são atualizados conforme o processo ocorre.

```bash
curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"
```

Uma transmissão que não existe em sua conta retorna `404`.

---

## Atualizar uma transmissão

`PUT /broadcasts/{broadcastId}` — envie apenas os campos que deseja alterar. Você também pode endereçar uma única chave dentro de um objeto aninhado com um caminho pontilhado, ex.: `"whats_app_template.body"`.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});
```

Um corpo vazio retorna `400`. Duas regras importantes:

- **`opener_media` é tudo ou nada.** Envie o objeto completo ou `null` para remover o anexo. Um caminho pontilhado dentro dele (`opener_media.name`) é rejeitado com `400`, porque um anexo parcialmente atualizado descreveria um arquivo que não existe.
- **O status não é editável.** Use [lançar](#launch-a-broadcast), [pausar](#pause-and-resume) e [retomar](#pause-and-resume).

---

## A mensagem de abertura

Cada transmissão carrega seu conteúdo inicial em `whats_app_template`. O que isso significa depende do canal:

- **WhatsApp Business** — deve ser um modelo aprovado pelo WhatsApp. Use um dos dois endpoints abaixo.
- **Qualquer outro canal** (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — o `body` do mesmo campo é simplesmente o texto que será enviado. Enviá-lo através do endpoint abaixo o armazena e o marca como pronto, sem envolver o WhatsApp.

### Enviar um modelo para aprovação

`POST /broadcasts/{broadcastId}/template`

| Campo | Obrigatório | Descrição |
|---|---|---|
| `body` | Sim | O texto da mensagem, com até 1024 caracteres. Use os placeholders `{{variable}}` para personalização. |
| `name` | Não | Nome do modelo. O padrão é o nome da transmissão. |
| `language` | Não | Código do idioma. O padrão é `en`. |
| `category` | Não | `marketing` (padrão), `utility`, `authentication` ou `authentication-international`. É assim que o envio é precificado, portanto, mantenha a precisão. |
| `variables` | Não | Os nomes dos placeholders, na ordem em que aparecem. Deixe de fora e eles serão lidos a partir do corpo — o que geralmente é o que você deseja, pois o envio os preenche a partir de cada contato. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, our June offer is live until Friday.",
    "language": "en",
    "category": "marketing"
  }'
```

**Resposta** (`200`)

```json
{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }
```

`template_status` é o que o WhatsApp informa: `pending` enquanto está sendo analisado, `approved` quando está utilizável, `rejected` se foi recusado. Em um canal que não seja WhatsApp, ele retorna diretamente como `approved` com `template_sid: null` — nada a analisar.

Coisas que impedirão você:

- Enviar enquanto um modelo anterior ainda está em análise retorna `400`. Aguarde a decisão primeiro.
- Editar um modelo que já está aprovado mantém o aprovado ativo até que o novo retorne, para que uma transmissão em andamento nunca perca seu conteúdo inicial.
- Em um número de WhatsApp conectado diretamente via Meta, uma transmissão com imagem ou vídeo anexado não pode ser enviada (`400`) — anexos são suportados na via gerenciada do WhatsApp Business e no WhatsApp Web.

### Usar um modelo que você já teve aprovado

`POST /broadcasts/{broadcastId}/template/select` — copia um modelo já aprovado da sua [biblioteca de modelos](templates.md) para a transmissão, portanto, não há nada pelo que esperar.

| Campo | Obrigatório | Descrição |
|---|---|---|
| `template_id` | Sim | O id de um modelo aprovado em sua conta. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tpl_abc123" }'
```

**Resposta** (`200`)

```json
{
  "success": true,
  "broadcast_id": "bcd123abc456",
  "template_status": "approved",
  "template_sid": "HX0123...",
  "body": "Hi {{first_name}}, our June offer is live until Friday.",
  "name": "june_promo",
  "language": "en",
  "variables": ["first_name"],
  "category": "marketing"
}
```

A aprovação é verificada do nosso lado a partir do registro da biblioteca — você sempre envia apenas o id. Você recebe um `400` se a transmissão não for um rascunho do WhatsApp, se o modelo não estiver aprovado, se for um modelo de acompanhamento em vez de um inicial, ou se a transmissão tiver um anexo (modelos da biblioteca são apenas texto). Um id de modelo que não está em sua conta retorna `404`.

---

## Estimar o custo

`POST /broadcasts/{broadcastId}/estimate-cost` — precifica o envio antes de você se comprometer com ele. Disponível em transmissões `whatsapp` e `sms`; qualquer outro canal retorna `400`. A transmissão precisa de um `list_id`, já que a estimativa conta o público.

```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"
```

**Resposta do WhatsApp** (`200`) — créditos, detalhados por país de destino:

```json
{
  "success": true,
  "channel": "whatsapp",
  "billing_mode": "credits",
  "data": {
    "countries": [
      { "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
      { "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
    ],
    "totalContacts": 240,
    "totalTemplateCost": 270,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}
```

**Resposta por SMS** (`200`) — Dólares americanos, com base nos preços em tempo real da Twilio para sua própria conta Twilio:

```json
{
  "success": true,
  "channel": "sms",
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 240,
    "messageLength": 118,
    "segmentsPerMessage": 1,
    "totalSegments": 240,
    "estimatedCostUsd": 1.788,
    "priceUnit": "USD",
    "billedByTwilio": true,
    "billing_mode": "twilio_direct",
    "service_messages_billable_soon": false
  }
}
```

**Leia `billing_mode` antes de exibir um número.** Ele informa quem está sendo cobrado:

| `billing_mode` | Quem paga | O que os valores significam |
|---|---|---|
| `credits` | Sua conta <span data-t="appName">Your AI Connector</span> | `totalTemplateCost` e os valores por país são créditos. |
| `twilio_direct` | Sua própria conta Twilio | `estimatedCostUsd` é o que a Twilio cobrará de você. |
| `meta_waba_direct` | Sua própria conta do WhatsApp Business, cobrada pela Meta | Cada valor de crédito retorna `null` — propositalmente, para que nunca seja confundido com "gratuito". As contagens de país e contato ainda são precisas. |

SMS sem credenciais da Twilio conectadas ainda retorna as contagens de segmento, com `estimatedCostUsd: 0` — não há preços para consultar.

---

## Iniciar uma transmissão

`POST /broadcasts/{broadcastId}/launch`

O início verifica tudo primeiro e só então prossegue com a transmissão. Não existe início parcial: ou ela começa, ou nada muda e você recebe uma mensagem de erro explicando o motivo.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);
```

**Python**

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())
```

**Resposta** (`200`)

```json
{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }
```

`status` é onde a transmissão foi parar:

- `Scheduled` — `execution_date` está no futuro.
- `Sending` — começou agora.
- `Pending Approval` — o modelo do WhatsApp ainda está em análise. Ele será enviado assim que o modelo for aprovado; não chame o início novamente.

Apenas uma `Draft` (ou uma transmissão `Pending Approval` cujo modelo tenha sido aprovado desde então) pode ser iniciada — qualquer outra coisa retorna `400`.

### Por que um início é recusado

Cada um desses retorna como `400` com uma mensagem `error` em linguagem simples:

| Problema | O que corrigir |
|---|---|
| Sem público | Defina `list_id` (ou anexe contatos) antes de iniciar. |
| Sem mensagem de abertura | Defina o abridor — veja [A mensagem de abertura](#the-opening-message). |
| Anexo em SMS | SMS não pode conter imagem ou vídeo. Remova o anexo ou mova a transmissão para o WhatsApp. |
| Anexo não corresponde ao modelo aprovado | No WhatsApp, a mídia reside dentro do modelo aprovado, portanto, trocar o anexo posteriormente significa reenviar o modelo. |
| Modelo rejeitado | Reescreva a mensagem e envie-a novamente. |
| Modelo nunca enviado | Envie-o (ou selecione um aprovado) primeiro. |
| Modelo aprovado, mas ausente da sua conta do WhatsApp | Geralmente um modelo aprovado antes da conclusão da conexão do número. Envie-o novamente. |
| Sem remetente conectado para o canal | Conecte o canal primeiro — veja [Canais](channels.md). |
| Canal apenas de resposta | TikTok e Skool não permitem que uma empresa inicie uma conversa, portanto, não podem ser usados para transmissão. |
| Já armado | A transmissão já tem um envio agendado. Pause-a antes de iniciar novamente. |
| Ainda aguardando aprovação | Ela será enviada automaticamente quando o modelo for aprovado. |
| Conta do WhatsApp Business bloqueada pela Meta | A Meta interrompeu conversas iniciadas pela empresa em sua própria conta do WhatsApp Business — normalmente um problema de método de pagamento. Corrija no Gerenciador de Negócios da Meta. |
| Iniciado a partir de uma campanha clássica | Inicie-a a partir do editor de campanhas. Veja [campanhas clássicas em Transmissões](#broadcasts-that-mirror-a-classic-campaign). |

---

## Pausar e retomar

`POST /broadcasts/{broadcastId}/pause` interrompe uma transmissão `Sending` ou `Scheduled` e cancela tudo o que estiver na fila.

```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"
```

Pausar uma transmissão `Pending Approval` a coloca de volta em `Draft` — nada foi agendado ainda, então não há nada para retomar. Qualquer outro status retorna `400`.

`POST /broadcasts/{broadcastId}/resume` reinicia uma transmissão `Paused`:

```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"
```

**Resposta** (`200`)

```json
{ "success": true, "broadcast_id": "bcd123abc456" }
```

Ela retoma em `Sending`, ou volta para `Scheduled` se o seu `execution_date` ainda estiver no futuro. Apenas uma transmissão `Paused` pode ser retomada.

---

## Continuar enviando após uma pausa por baixo engajamento

`POST /broadcasts/{broadcastId}/override-engagement-guard`

Enquanto uma transmissão é enviada em lotes, medimos quantas pessoas responderam a cada lote antes de iniciar o próximo. Se quase ninguém estiver respondendo, a transmissão pausa automaticamente — um envio que continua insistindo no silêncio é a maneira mais rápida de ter um número filtrado ou bloqueado. É o botão **Continuar mesmo assim** no painel.

Como a taxa de resposta que causou a pausa não pode mudar enquanto a transmissão está parada, um [resume](#pause-and-resume) simples seria pausado novamente pela próxima verificação. Este endpoint é a decisão de continuar mesmo assim: ele registra a substituição nessa transmissão específica e remove a pausa na mesma chamada, caso a transmissão tenha sido pausada por baixo engajamento.

```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"
```

**Resposta** (`200`)

```json
{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }
```

- `resumed: true` — a transmissão foi pausada por baixo engajamento e agora está rodando novamente; `status` é onde ela foi retomada.
- `resumed: false` — nada foi removido, a substituição é simplesmente registrada para verificações futuras. Isso é o que você recebe se a transmissão nunca foi pausada ou foi pausada por um motivo diferente (você a pausou manualmente, um limite de envio foi atingido ou muitos envios apresentaram erro). Essas pausas não são removidas aqui — retome-a você mesmo depois de ter resolvido a causa.

A substituição se aplica apenas a esta transmissão. Não é uma configuração de conta e é seguro chamar duas vezes.

---

## Duplicar uma transmissão

`POST /broadcasts/{broadcastId}/duplicate` — copia o público, a mensagem e as configurações para uma nova `Draft`. Tudo sobre a execução anterior (contadores, lotes, agendamento, estatísticas de resposta) começa do zero.

| Campo | Obrigatório | Descrição |
|---|---|---|
| `to_channel` | Não | Cria a cópia em um canal diferente. É assim que você envia a mesma coisa em dois canais — uma transmissão sempre tem apenas um. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'
```

**Resposta** (`201`)

```json
{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }
```

Uma cópia nunca herda uma aprovação ativa do WhatsApp: em uma cópia do WhatsApp, o modelo vem precisando da sua confirmação e, em uma cópia para outro canal, ele é descartado e o texto se torna o abridor simples. Copiar para SMS também descarta qualquer anexo, já que SMS não pode enviar um.

---

## Excluir uma transmissão

`DELETE /broadcasts/{broadcastId}`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"
```

Uma `Sending` ou `Scheduled` transmissão é recusada com `400` — pause-a primeiro.

---

## Transmissões que espelham uma campanha clássica

Campanhas clássicas que enviam mensagens também aparecem em Transmissões, e a API as retorna junto com as transmissões nativas (elas carregam um `source_campaign_id`). Elas se comportam de maneira um pouco diferente, porque a campanha permanece no controle:

- **Editar** o público, a mensagem ou o agendamento funciona e é aplicado diretamente à campanha.
- **Canal, agente de resposta, anexo e todos os contadores de execução são somente leitura** aqui — `400` se você tentar alterá-los. Altere-os na campanha.
- **Lançar** retorna `400` direcionando você para o editor da campanha.
- **Pausar e retomar** funcionam e agem sobre a campanha.
- **Excluir** retorna `400` — exclua a campanha em vez disso, e sua entrada em Transmissões será removida com ela.
- **Duplicar** fornece uma transmissão nativa independente, que é a maneira suportada de mover uma campanha comprovada.

---

## Erros

Solicitações com falha retornam `{"success": false, "error": "<message>"}` com estes status:

| Status | Significado |
|---|---|
| `400` | Algo sobre a solicitação ou o estado da transmissão está incorreto — um campo ausente, um anexo inválido ou um lançamento/pausa/retomada/exclusão que não é permitido no status atual da transmissão. A mensagem `error` indica o motivo. |
| `401` | Chave de API ausente ou inválida. |
| `403` | Seu plano não inclui acesso à API. |
| `404` | Não existe tal transmissão em sua conta (ou, na seleção de modelo, não existe tal modelo). |
| `429` | Limite de taxa excedido. Aguarde e tente novamente. |
| `500` | Algo deu errado do nosso lado. Tente novamente após uma breve espera. |

---

## Próximos passos

- [Guia de Transmissões](../broadcasts/broadcasts.md) — o produto por trás desses endpoints, incluindo ritmo e comportamento de segurança
- [API de Contatos](contacts.md) — crie a lista para a qual uma transmissão envia
- [API de Modelos](templates.md) — gerencie os modelos aprovados do WhatsApp que você pode selecionar
- [API de Webhooks](webhooks.md) — inscreva-se em `Broadcast Started` e `Broadcast Completed` em vez de fazer polling