# 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, também nomeia o Agente de IA que lida com as respostas recebidas. A API de Transmissões permite-lhe criar, definir preços, lançar e monitorizar esses envios a partir do seu próprio código em vez do painel de controlo. Para o produto em si, consulte o [guia de Transmissões](../broadcasts/broadcasts.md).

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

Todos os exemplos abaixo mostram o formato de consulta `?apiKey=` em cURL e o cabeçalho `X-API-Key` em JavaScript e Python — qualquer um funciona em todos os endpoints.

> **No explorador da API.** Todos os endpoints nesta página estão na especificação OpenAPI publicada, pelo que pode consultar os seus campos exatos e executar pedidos em tempo real no [explorador da API](reference.md).


---

## Como um envio é estruturado

O envio de uma transmissão requer quatro chamadas, não apenas uma:

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

Nada é enviado até que 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 são devolvidos como milissegundos da época** (`execution_date`, `created_at`, `last_modified_at`, …), e qualquer referência de contacto é devolvida como uma string de caminho como `contacts/uid_whatsapp_15551234567`.

### Campos que define

| Campo | Descrição |
|---|---|
| `name` | Como a transmissão é chamada no painel de controlo. |
| `channel` | O único canal através do qual esta transmissão envia: `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 noutro local, [duplique-a para outro canal](#duplicate-a-broadcast). `tiktok` e `skool` são apenas para respostas 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 equipa. |
| `list_id` | A lista de contactos para a qual enviar. É assim que define o público a partir da API — consulte [Contactos](contacts.md) para criar e preencher listas. |
| `list_name` | Nome de exibição mostrado junto à transmissão. Cosmético. |
| `send_to_new_list_members` | `true` mantém a transmissão ativa para que qualquer pessoa adicionada à lista mais tarde também receba a mensagem de abertura. |
| `whats_app_template` | A mensagem de abertura. No WhatsApp Business, é um modelo real aprovado; em qualquer outro canal, o seu `body` é usado como o texto de abertura simples. Defina-o através dos [endpoints de modelos](#the-opening-message), não manualmente. |
| `opener_media` | Uma imagem ou vídeo enviado com a abertura. Envie sempre o objeto completo (ou `null` para o remover) — 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 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 é ativado acima de 50 contactos — para um público recetivo que precisa da mensagem agora. Não levanta o limite diário de envio do próprio canal. |
| `batch_size` | Quantos contactos por lote ao enviar gradualmente. |
| `follow_up_config` | A cadeia de seguimento para contactos que nunca respondem. |

Qualquer coisa que envie como `user_id`, `id`, `status` ou `source_campaign_id` é ignorada na criação e descartada na atualização — o estado apenas muda através dos endpoints de lançamento, pausa e retoma 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 contactos individuais anexados a partir do painel de controlo, lidos como strings de caminho). Leia-os, não os escreva.

### Estados

| Estado | Significado |
|---|---|
| `Draft` | A ser criado. Nada está agendado. |
| `Pending Approval` | Lançado, mas o seu modelo de WhatsApp ainda aguarda uma decisão. Começa a enviar automaticamente assim que o modelo for aprovado — não precisa de lançar novamente. |
| `Scheduled` | Lançado com um `execution_date` futuro. |
| `Sending` | A enviar ativamente (uma difusão preparada para novos membros da lista permanece aqui enquanto aguarda por eles). |
| `Paused` | Suspenso — por si, ou automaticamente por uma verificação de segurança. |
| `Sent` | Concluído. |
| `Failed` | Concluído com mais de metade dos envios falhados. |

---

## Criar uma difusã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 difusões

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

**Parâmetros de consulta**

| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| `status` | Não | Devolve apenas difusões num determinado estado, p. ex. `Sending`. Corresponda exatamente à grafia na [tabela de estados](#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 difusão

`GET /broadcasts/{broadcastId}` — devolve `{ "success": true, "broadcast": { ... } }`. Utilize-o para consultar um envio em curso: `total_contacts_sent`, `unique_contacts_replied`, `overall_reply_rate` e `credits_used` são atualizados à medida que o processo decorre.

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

Uma difusão que não existe na sua conta devolve `404`.

---

## Atualizar uma difusão

`PUT /broadcasts/{broadcastId}` — envie apenas os campos que pretende alterar. Também pode endereçar uma única chave dentro de um objeto aninhado com um caminho pontuado, p. 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 devolve `400`. Duas regras que vale a pena conhecer:

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

---

## A mensagem de abertura

Cada difusão contém o seu elemento de abertura em `whats_app_template`. O que isso significa depende do canal:

- **WhatsApp Business** — tem de ser um modelo aprovado pelo WhatsApp. Utilize um dos dois endpoints abaixo.
- **Todos os outros canais** (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — o `body` do mesmo campo é simplesmente o texto que é enviado. Submetê-lo através do endpoint abaixo armazena-o e marca-o como pronto sem envolver o WhatsApp.

### Submeter um modelo para aprovação

`POST /broadcasts/{broadcastId}/template`

| Campo | Obrigatório | Descrição |
|---|---|---|
| `body` | Sim | O texto da mensagem, até 1024 caracteres. Utilize marcadores de posição `{{variable}}` para personalização. |
| `name` | Não | Nome do modelo. Por predefinição, assume o nome da difusão. |
| `language` | Não | Código do idioma. Por predefinição, assume `en`. |
| `category` | Não | `marketing` (predefinição), `utility`, `authentication` ou `authentication-international`. É o valor pelo qual o envio é taxado, por isso seja rigoroso. |
| `variables` | Não | Os nomes dos marcadores de posição, pela ordem em que aparecem. Se omitir, são lidos a partir do corpo — que é normalmente o que pretende, uma vez que o envio os preenche a partir de cada contacto. |

```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 indica: `pending` enquanto está a ser revisto, `approved` quando está pronto a utilizar, `rejected` se foi recusado. Num canal que não seja WhatsApp, a resposta é diretamente `approved` com `template_sid: null` — não há nada para rever.

Coisas que o impedirão:

- Submeter enquanto um modelo anterior ainda está sob revisão devolve `400`. Aguarde primeiro pela decisão.
- Editar um modelo que está atualmente aprovado mantém o aprovado ativo até que o novo seja processado, para que uma difusão em curso nunca perca o seu elemento de abertura.
- Num número WhatsApp ligado diretamente através da Meta, uma difusão com uma imagem ou vídeo anexado não pode ser submetida (`400`) — os anexos são suportados na via gerida do WhatsApp Business e no WhatsApp Web.

### Utilizar um modelo que já foi aprovado

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

| Campo | Obrigatório | Descrição |
|---|---|---|
| `template_id` | Sim | O id de um modelo aprovado na 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 registo da biblioteca — envia apenas o id. Recebe um `400` se a difusão não for um rascunho do WhatsApp, se o modelo não estiver aprovado, se for um modelo de seguimento em vez de um de abertura, ou se a difusão tiver um anexo (os modelos da biblioteca são apenas de texto). Um id de modelo que não esteja na sua conta devolve `404`.

---

## Estimar o custo

`POST /broadcasts/{broadcastId}/estimate-cost` — calcula o preço do envio antes de o confirmar. Disponível em difusões `whatsapp` e `sms`; qualquer outro canal devolve `400`. A difusão necessita de um `list_id`, uma vez que a estimativa contabiliza a audiência.

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

**Resposta do WhatsApp** (`200`) — créditos, discriminados 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 a 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 mostrar um número.** Indica-lhe quem está a ser cobrado:

| `billing_mode` | Quem paga | O que significam os valores |
|---|---|---|
| `credits` | A sua conta <span data-t="appName">Your AI Connector</span> | `totalTemplateCost` e os valores por país são créditos. |
| `twilio_direct` | A sua própria conta Twilio | `estimatedCostUsd` é o que a Twilio lhe cobrará. |
| `meta_waba_direct` | A sua própria conta WhatsApp Business, cobrada pela Meta | Cada valor de crédito aparece como `null` — propositadamente, para que nunca seja confundido com "gratuito". As contagens de países e contactos continuam a ser precisas. |

O SMS sem credenciais Twilio ligadas continua a devolver as contagens de segmentos, com `estimatedCostUsd: 0` — não existem preços a consultar.

---

## Iniciar uma difusão

`POST /broadcasts/{broadcastId}/launch`

O início verifica tudo primeiro e só depois avança com a difusão. Não existe início parcial: ou começa, ou nada muda e recebe um erro a explicar 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 entregue:

- `Scheduled` — `execution_date` está no futuro.
- `Sending` — começou agora.
- `Pending Approval` — o modelo do WhatsApp ainda está sob análise. Será enviado automaticamente assim que o modelo for aprovado; não chame o lançamento novamente.

Apenas uma transmissão `Draft` (ou uma `Pending Approval` cujo modelo tenha sido aprovado entretanto) pode ser lançada — qualquer outra coisa devolve `400`.

### Por que um lançamento é recusado

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

| Problema | O que corrigir |
|---|---|
| Sem público | Defina `list_id` (ou anexe contactos) antes de lançar. |
| Sem mensagem de abertura | Defina a abertura — veja [A mensagem de abertura](#the-opening-message). |
| Anexo em SMS | SMS não pode conter uma imagem ou vídeo. Remova o anexo ou mova a transmissão para o WhatsApp. |
| Anexo não corresponde ao modelo aprovado | No WhatsApp, o conteúdo multimédia reside dentro do modelo aprovado, por isso, trocar o anexo posteriormente significa submeter o modelo novamente. |
| Modelo rejeitado | Reescreva a mensagem e submeta-a novamente. |
| Modelo nunca submetido | Submeta-o (ou selecione um aprovado) primeiro. |
| Modelo aprovado mas em falta na sua conta WhatsApp | Geralmente um modelo aprovado antes de o número terminar a ligação. Submeta-o novamente. |
| Sem remetente ligado para o canal | Ligue o canal primeiro — veja [Canais](channels.md). |
| Canal apenas de resposta | TikTok e Skool não permitem que uma empresa inicie uma conversa, por isso não podem ser usados para transmissões. |
| Já armado | A transmissão já tem um envio agendado. Pause-a antes de lançar novamente. |
| Ainda a aguardar aprovação | Será enviada automaticamente quando o modelo for aprovado. |
| Conta WhatsApp Business bloqueada pela Meta | A Meta interrompeu as conversas iniciadas pela empresa na sua própria conta WhatsApp Business — normalmente um problema de método de pagamento. Corrija-o no Gestor de Negócios da Meta. |
| Iniciada a partir de uma campanha clássica | Lance-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` para 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` coloca-a de volta em `Draft` — nada estava agendado, por isso não há nada para retomar. Qualquer outro estado devolve `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" }
```

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 o envio após uma pausa por baixo envolvimento

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

Enquanto uma transmissão é enviada em lotes, medimos quantas pessoas responderam a cada lote antes de iniciar o seguinte. Se quase ninguém responder, a transmissão pausa-se automaticamente — um envio que continua a insistir no silêncio é a forma mais rápida de um número ser filtrado ou bloqueado. É o botão **Continuar mesmo assim** no painel de controlo.

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 apenas pausado novamente pela verificação seguinte. Este endpoint representa a decisão de continuar mesmo assim: regista a anulação nessa transmissão específica e levanta a pausa na mesma chamada, caso a transmissão tenha sido pausada por baixo envolvimento.

```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 envolvimento e está agora a decorrer novamente; `status` é o estado para onde foi retomada.
- `resumed: false` — nada foi levantado, a anulação é simplesmente registada para verificações futuras. É isto que obtém se a transmissão nunca tiver sido pausada, ou se tiver sido pausada por um motivo diferente (pausou-a manualmente, atingiu um limite de envio ou demasiados envios deram erro). Essas pausas não são levantadas aqui — retome-a manualmente depois de resolver a causa.

A anulação aplica-se apenas a esta transmissão. Não é uma definição da conta e é seguro chamar duas vezes.

---

## Duplicar uma transmissão

`POST /broadcasts/{broadcastId}/duplicate` — copia o público, a mensagem e as definições para uma nova `Draft`. Tudo o que diz respeito à 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 num canal diferente. É assim que envia a mesma coisa em dois canais — uma transmissão só tem um canal. |

```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: numa cópia do WhatsApp, o modelo é transferido a necessitar da sua confirmação e, numa cópia para outro canal, é removido e o texto torna-se o conteúdo simples. Copiar para SMS também remove qualquer anexo, uma vez que o SMS não permite o envio de anexos.

---

## Eliminar uma transmissão

`DELETE /broadcasts/{broadcastId}`

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

Uma difusão `Sending` ou `Scheduled` é recusada com `400` — coloque-a primeiro em pausa.

---

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

As campanhas clássicas que enviam mensagens também aparecem nas Difusões, e a API devolve-as juntamente com as difusões nativas (possuem um `source_campaign_id`). Comportam-se de forma ligeiramente diferente, porque a campanha continua a estar no comando:

- **Editar** o público-alvo, a mensagem ou o agendamento funciona e é aplicado na campanha.
- **O canal, o agente de resposta, o anexo e todos os contadores de execução são apenas de leitura** aqui — `400` se tentar alterá-los. Altere-os na campanha.
- **Iniciar** devolve `400`, direcionando-o para o editor da campanha.
- **Pausar e retomar** funcionam e atuam sobre a campanha.
- **Eliminar** devolve `400` — elimine a campanha em vez disso, e a sua entrada nas Difusões será removida com ela.
- **Duplicar** cria uma difusão nativa independente, que é a forma suportada de migrar uma campanha comprovada.

---

## Erros

Os pedidos falhados devolvem `{"success": false, "error": "<message>"}` com estes estados:

| Estado | Significado |
|---|---|
| `400` | Algo no pedido ou no estado da difusão está incorreto — um campo em falta, um anexo inválido ou uma ação de iniciar/pausar/retomar/eliminar que não é permitida no estado atual da difusão. A mensagem `error` indica o motivo. |
| `401` | Chave de API em falta ou inválida. |
| `403` | O seu plano não inclui acesso à API. |
| `404` | Essa difusão não existe na sua conta (ou, na seleção de modelos, esse modelo não existe). |
| `429` | Limite de taxa atingido. Aguarde e tente novamente. |
| `500` | Algo correu mal do nosso lado. Tente novamente após uma breve espera. |

---

## Próximos passos

- [Guia de Difusões](../broadcasts/broadcasts.md) — o produto por detrás destes endpoints, incluindo o ritmo e o comportamento de segurança
- [API de Contactos](contacts.md) — crie a lista para a qual uma difusão é enviada
- [API de Modelos](templates.md) — gira os modelos WhatsApp aprovados que pode selecionar
- [API de Webhooks](webhooks.md) — subscreva `Broadcast Started` e `Broadcast Completed` em vez de consultar