# API Broadcast

Un **broadcast** è un invio in uscita: un pubblico, un messaggio di apertura, un canale e una pianificazione. Facoltativamente, nomina anche l'Agente AI che gestisce le risposte ricevute. L'API Broadcast ti consente di creare, prezzare, lanciare e monitorare tali invii dal tuo codice invece che dalla dashboard. Per il prodotto in sé, consulta la [guida ai Broadcast](../broadcasts/broadcasts.md).

- **URL di base** — `https://api.youraiconnector.com/v1`
- **Autenticazione** — la tua chiave API (vedi [Autenticazione](authentication.md))
- **Errori e paginazione** — vedi [Errori e paginazione](errors-and-pagination.md)

Tutti gli esempi seguenti mostrano il formato di query `?apiKey=` in cURL e l'intestazione `X-API-Key` in JavaScript e Python; entrambi funzionano su ogni endpoint.

> **Nell'API explorer.** Ogni endpoint in questa pagina è presente nella specifica OpenAPI pubblicata, quindi puoi consultare i suoi campi esatti ed eseguire richieste live nell'[API explorer](reference.md).


---

## Come viene composto un invio

L'invio di un broadcast richiede quattro chiamate, non una:

1. **Crea** il broadcast con il suo pubblico, canale e pianificazione: inizia come `Draft`.
2. **Imposta il messaggio di apertura.** Su WhatsApp Business significa inviare un modello per l'approvazione (o sceglierne uno già approvato). Su ogni altro canale è testo semplice.
3. **Stima il costo** se vuoi verificare il prezzo prima di spendere qualcosa (facoltativo).
4. **Lancialo.** Il lancio esegue un controllo completo — pubblico, messaggio, approvazione del modello, mittente collegato — e avvia l'invio o ti dice esattamente cosa manca.

Non viene inviato nulla finché non chiami il lancio.

---

## L'oggetto broadcast

```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
}
```

**I timestamp vengono restituiti come millisecondi dall'epoca** (`execution_date`, `created_at`, `last_modified_at`, …), e qualsiasi riferimento al contatto viene restituito come stringa di percorso come `contacts/uid_whatsapp_15551234567`.

### Campi che imposti

| Campo | Descrizione |
|---|---|
| `name` | Come viene chiamato il broadcast nella dashboard. |
| `channel` | L'unico canale su cui questo broadcast invia: `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `messenger`, `facebook`, `telegram`, `instagram_private`, `line`, `viber`, `imessage`, `email`, `chat_widget`, `custom_channel`. Un broadcast ha esattamente un canale: per inviare la stessa cosa altrove, [duplicalo su un altro canale](#duplicate-a-broadcast). `tiktok` e `skool` sono solo per le risposte e non possono mai essere utilizzati per un broadcast. |
| `agent_id` | L'Agente AI che risponde ai messaggi. Lascialo `null` e le risposte finiranno invece nella tua casella di posta del team. |
| `list_id` | La lista contatti a cui inviare. È così che imposti il pubblico dall'API: vedi [Contatti](contacts.md) per creare e popolare le liste. |
| `list_name` | Nome visualizzato accanto al broadcast. Cosmetico. |
| `send_to_new_list_members` | `true` mantiene il broadcast attivo in modo che chiunque venga aggiunto alla lista in seguito riceva anch'egli il messaggio di apertura. |
| `whats_app_template` | Il messaggio di apertura. Su WhatsApp Business è un vero modello approvato; su ogni altro canale il suo `body` viene utilizzato come testo di apertura semplice. Impostalo tramite gli [endpoint dei modelli](#the-opening-message), non manualmente. |
| `opener_media` | Un'immagine o un video inviato con l'apertura. Invia sempre l'intero oggetto (o `null` per rimuoverlo): scrivere singoli campi al suo interno viene rifiutato. Non supportato su SMS. |
| `execution_date` | Quando inviare. Invia un timestamp ISO 8601 o millisecondi dall'epoca. Una data futura pianifica l'invio; omettilo (o usane una passata) per inviare non appena effettui il lancio. |
| `drip_mode` | `true` distribuisce l'invio in batch nel tempo invece che tutto in una volta. |
| `time_critical` | `true` esclude la distribuzione automatica che si attiva sopra i 50 contatti, per un pubblico caldo che necessita del messaggio subito. Non solleva il limite di invio giornaliero del canale. |
| `batch_size` | Quanti contatti per batch durante l'invio graduale. |
| `follow_up_config` | La catena di follow-up per i contatti che non rispondono mai. |

Tutto ciò che invii come `user_id`, `id`, `status` o `source_campaign_id` viene ignorato durante la creazione e rimosso durante l'aggiornamento: lo stato passa solo attraverso gli endpoint di lancio, pausa e ripresa sottostanti.

### Campi gestiti dalla piattaforma

`status`, `total_contacts_sent`, `unique_contacts_replied`, `overall_reply_rate`, `credits_used`, `paused_reason`, `completion_summary`, i contatori dei batch e `contacts` (i singoli contatti allegati dalla dashboard, letti come stringhe di percorso). Leggili, non scriverli.

### Stati

| Stato | Significato |
|---|---|
| `Draft` | In fase di creazione. Nulla è pianificato. |
| `Pending Approval` | Lanciato, ma il suo modello WhatsApp è in attesa di una decisione. Inizierà l'invio automaticamente una volta approvato il modello: non è necessario lanciarlo di nuovo. |
| `Scheduled` | Lanciato con una `execution_date` futura. |
| `Sending` | In fase di invio (una trasmissione predisposta per nuovi membri della lista rimane qui in attesa di essi). |
| `Paused` | In pausa: da parte tua o automaticamente a causa di un controllo di sicurezza. |
| `Sent` | Completato. |
| `Failed` | Completato con più della metà degli invii falliti. |

---

## Crea una trasmissione

`POST /broadcasts` — crea una `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"])
```

**Risposta** (`201`)

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

---

## Elenca trasmissioni

`GET /broadcasts` — ogni trasmissione sull'account, dalla più recente. |

**Parametri di query**

| Parametro | Obbligatorio | Descrizione |
|---|---|---|
| `status` | No | Restituisce solo le trasmissioni in un determinato stato, ad es. `Sending`. La grafia deve corrispondere esattamente a quella nella [tabella degli stati](#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"]
```

**Risposta** (`200`)

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

---

## Ottieni una trasmissione

`GET /broadcasts/{broadcastId}` — restituisce `{ "success": true, "broadcast": { ... } }`. Usalo per monitorare un invio in corso: `total_contacts_sent`, `unique_contacts_replied`, `overall_reply_rate` e `credits_used` si aggiornano man mano. |

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

Una trasmissione che non esiste sul tuo account restituisce `404`.

---

## Aggiorna una trasmissione

`PUT /broadcasts/{broadcastId}` — invia solo i campi che desideri modificare. Puoi anche indirizzare una singola chiave all'interno di un oggetto nidificato con un percorso puntato, ad es. `"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" }),
});
```

Un corpo vuoto restituisce `400`. Due regole da tenere a mente:

- **`opener_media` è tutto o niente.** Invia l'oggetto completo o `null` per rimuovere l'allegato. Un percorso puntato al suo interno (`opener_media.name`) viene rifiutato con `400`, poiché un allegato aggiornato parzialmente descriverebbe un file inesistente.
- **Lo stato non è modificabile.** Usa [lancio](#launch-a-broadcast), [pausa](#pause-and-resume) e [riprendi](#pause-and-resume).

---

## Il messaggio di apertura

Ogni trasmissione porta il suo messaggio di apertura in `whats_app_template`. Il significato dipende dal canale:

- **WhatsApp Business** — deve essere un modello approvato da WhatsApp. Utilizza uno dei due endpoint sottostanti.
- **Ogni altro canale** (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — il campo `body` corrisponde semplicemente al testo che viene inviato. L'invio tramite l'endpoint sottostante lo memorizza e lo contrassegna come pronto senza coinvolgere WhatsApp.

### Invia un modello per l'approvazione

`POST /broadcasts/{broadcastId}/template`

| Campo | Obbligatorio | Descrizione |
|---|---|---|
| `body` | Sì | Il testo del messaggio, fino a 1024 caratteri. Usa i segnaposto `{{variable}}` per la personalizzazione. |
| `name` | No | Nome del modello. Per impostazione predefinita è il nome della trasmissione. |
| `language` | No | Codice lingua. Per impostazione predefinita è `en`. |
| `category` | No | `marketing` (predefinito), `utility`, `authentication` o `authentication-international`. Questo determina il prezzo dell'invio, quindi sii preciso. |
| `variables` | No | I nomi dei segnaposto, nell'ordine in cui appaiono. Omettilo e verranno letti dal corpo del messaggio — che è solitamente ciò che desideri, poiché l'invio li compila in base a ciascun contatto. |

```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"
  }'
```

**Risposta** (`200`)

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

`template_status` è ciò che dice WhatsApp: `pending` mentre è in fase di revisione, `approved` quando è utilizzabile, `rejected` se è stato rifiutato. Su un canale non WhatsApp, viene restituito direttamente come `approved` con `template_sid: null` — non c'è nulla da revisionare.

Cose che potrebbero bloccarti:

- L'invio mentre un modello precedente è ancora in fase di revisione restituisce `400`. Attendi prima la decisione.
- La modifica di un modello attualmente approvato mantiene attivo quello approvato finché non arriva il nuovo, in modo che una trasmissione in corso non perda mai il suo messaggio di apertura.
- Su un numero WhatsApp collegato direttamente tramite Meta, una trasmissione con un'immagine o un video allegato non può essere inviata (`400`) — gli allegati sono supportati sul canale WhatsApp Business gestito e su WhatsApp Web.

### Usa un modello già approvato

`POST /broadcasts/{broadcastId}/template/select` — copia un modello già approvato dalla tua [libreria modelli](templates.md) nella trasmissione, quindi non c'è nulla da attendere.

| Campo | Obbligatorio | Descrizione |
|---|---|---|
| `template_id` | Sì | L'id di un modello approvato sul tuo account. |

```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" }'
```

**Risposta** (`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"
}
```

L'approvazione viene verificata da parte nostra dal record della libreria — invii sempre solo l'id. Riceverai un `400` se la trasmissione non è una bozza WhatsApp, se il modello non è approvato, se si tratta di un modello di follow-up anziché di apertura, o se la trasmissione ha un allegato (i modelli della libreria sono solo testo). Un id modello che non è presente sul tuo account restituisce `404`.

---

## Stima il costo

`POST /broadcasts/{broadcastId}/estimate-cost` — calcola il prezzo dell'invio prima di confermarlo. Disponibile su trasmissioni `whatsapp` e `sms`; qualsiasi altro canale restituisce `400`. La trasmissione necessita di un `list_id`, poiché la stima conteggia il pubblico.

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

**Risposta WhatsApp** (`200`) — crediti, suddivisi per paese di destinazione:

```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
  }
}
```

**Risposta SMS** (`200`) — Dollari statunitensi, basati sui prezzi Twilio in tempo reale per il tuo account 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
  }
}
```

**Leggi `billing_mode` prima di mostrare un numero.** Ti indica chi viene fatturato:

| `billing_mode` | Chi paga | Cosa significano le cifre |
|---|---|---|
| `credits` | Il tuo account <span data-t="appName">Your AI Connector</span> | `totalTemplateCost` e le cifre per paese sono crediti. |
| `twilio_direct` | Il tuo account Twilio | `estimatedCostUsd` è ciò che Twilio ti addebiterà. |
| `meta_waba_direct` | Il tuo account WhatsApp Business, fatturato da Meta | Ogni cifra di credito viene restituita come `null` — deliberatamente, in modo che non venga mai scambiata per "gratuita". Il conteggio dei paesi e dei contatti rimane accurato. |

Gli SMS senza credenziali Twilio collegate restituiscono comunque il conteggio dei segmenti, con `estimatedCostUsd: 0` — non ci sono prezzi da consultare.

---

## Avvia una trasmissione

`POST /broadcasts/{broadcastId}/launch`

L'avvio controlla tutto prima di procedere con la trasmissione. Non esiste un avvio parziale: o si avvia, o non cambia nulla e ricevi un errore che ne spiega il 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())
```

**Risposta** (`200`)

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

`status` è dove è approdata la trasmissione:

- `Scheduled` — `execution_date` è nel futuro.
- `Sending` — è iniziata ora.
- `Pending Approval` — il modello WhatsApp è ancora in fase di revisione. Si invierà da solo non appena il modello sarà approvato; non richiamare l'avvio.

Solo una trasmissione `Draft` (o una `Pending Approval` il cui modello è stato approvato nel frattempo) può essere avviata — qualsiasi altra cosa restituisce `400`.

### Perché un avvio viene rifiutato

Ognuno di questi viene restituito come `400` con un messaggio `error` in linguaggio semplice:

| Problema | Cosa correggere |
|---|---|
| Nessun pubblico | Imposta `list_id` (o allega contatti) prima di avviare. |
| Nessun messaggio di apertura | Imposta l'apertura — vedi [Il messaggio di apertura](#the-opening-message). |
| Allegato su SMS | Gli SMS non possono contenere immagini o video. Rimuovi l'allegato o sposta la trasmissione su WhatsApp. |
| L'allegato non corrisponde al modello approvato | Su WhatsApp i media risiedono all'interno del modello approvato, quindi cambiare l'allegato in seguito significa dover inviare nuovamente il modello. |
| Modello rifiutato | Riscrivi il messaggio e invialo di nuovo. |
| Modello mai inviato | Invialo (o selezionane uno approvato) prima. |
| Modello approvato ma mancante dal tuo account WhatsApp | Di solito è un modello approvato prima che il numero finisse di connettersi. Invialo di nuovo. |
| Nessun mittente collegato per il canale | Collega prima il canale — vedi [Canali](channels.md). |
| Canale di sola risposta | TikTok e Skool non consentono a un'azienda di iniziare una conversazione, quindi non possono essere utilizzati per le trasmissioni. |
| Già armato | La trasmissione ha già un invio programmato. Mettila in pausa prima di avviarla di nuovo. |
| Ancora in attesa di approvazione | Si invierà da sola quando il modello sarà approvato. |
| Account WhatsApp Business bloccato da Meta | Meta ha interrotto le conversazioni avviate dall'azienda sul tuo account WhatsApp Business — solitamente un problema di metodo di pagamento. Risolvilo nel Business Manager di Meta. |
| Avviato da una campagna classica | Avvialo invece dall'editor delle campagne. Vedi [campagne classiche nelle Trasmissioni](#broadcasts-that-mirror-a-classic-campaign). |

---

## Metti in pausa e riprendi

`POST /broadcasts/{broadcastId}/pause` interrompe una trasmissione `Sending` o `Scheduled` ed elimina tutto ciò che è in coda.

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

Mettere in pausa una trasmissione `Pending Approval` la riporta a `Draft` invece: non era ancora programmato nulla, quindi non c'è nulla da riprendere. Qualsiasi altro stato restituisce `400`.

`POST /broadcasts/{broadcastId}/resume` riavvia una trasmissione `Paused`:

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

**Risposta** (`200`)

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

Riprende in `Sending`, o torna in `Scheduled` se il suo `execution_date` è ancora nel futuro. Solo una trasmissione `Paused` può essere ripresa.

---

## Continua l'invio dopo una pausa per basso coinvolgimento

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

Mentre una trasmissione invia in batch, misuriamo quante persone hanno risposto a ciascun batch prima di iniziare quello successivo. Se quasi nessuno risponde, la trasmissione si mette in pausa da sola: un invio che continua a spingere nel silenzio è il modo più rapido per far filtrare o bloccare un numero. Si tratta del pulsante **Continua comunque** nella dashboard.

Poiché il tasso di risposta che ha causato la pausa non può cambiare mentre la trasmissione è ferma, un semplice [resume](#pause-and-resume) verrebbe semplicemente messo di nuovo in pausa al controllo successivo. Questo endpoint rappresenta la decisione di continuare comunque: registra l'override su quella specifica trasmissione e rimuove la pausa nella stessa chiamata se la trasmissione era stata messa in pausa per basso coinvolgimento.

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

**Risposta** (`200`)

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

- `resumed: true` — la trasmissione era stata messa in pausa per basso coinvolgimento ed è ora di nuovo in esecuzione; `status` è lo stato in cui è ripresa.
- `resumed: false` — non è stato rimosso nulla, l'override viene semplicemente registrato per i controlli futuri. Questo è ciò che si ottiene se la trasmissione non è mai stata messa in pausa, o è stata messa in pausa per un motivo diverso (l'hai messa in pausa manualmente, è stato raggiunto un limite di invio o troppi invii hanno generato errori). Queste pause non vengono rimosse qui: riprendila tu stesso una volta risolta la causa.

L'override si applica solo a questa trasmissione. Non è un'impostazione dell'account ed è sicuro chiamarlo due volte.

---

## Duplica una trasmissione

`POST /broadcasts/{broadcastId}/duplicate` — copia il pubblico, il messaggio e le impostazioni in una nuova `Draft`. Tutto ciò che riguarda l'esecuzione precedente (contatori, batch, pianificazione, statistiche di risposta) riparte da zero.

| Campo | Obbligatorio | Descrizione |
|---|---|---|
| `to_channel` | No | Crea la copia su un canale diverso. È così che invii la stessa cosa su due canali: una trasmissione ne ha sempre e solo uno. |

```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" }'
```

**Risposta** (`201`)

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

Una copia non eredita mai un'approvazione WhatsApp attiva: su una copia WhatsApp il modello viene trasferito richiedendo la tua conferma, mentre su una copia verso un altro canale viene rimosso e il testo diventa l'apertura semplice. La copia su SMS rimuove anche qualsiasi allegato, poiché gli SMS non possono inviarne.

---

## Elimina una trasmissione

`DELETE /broadcasts/{broadcastId}`

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

Una trasmissione `Sending` o `Scheduled` viene rifiutata con `400`: mettila prima in pausa.

---

## Trasmissioni che rispecchiano una campagna classica

Le campagne classiche che inviano messaggi appaiono anche nelle Trasmissioni e l'API le restituisce insieme alle trasmissioni native (contengono un `source_campaign_id`). Si comportano in modo leggermente diverso, poiché la campagna rimane quella principale:

- **La modifica** del pubblico, del messaggio o della pianificazione funziona e viene applicata alla campagna.
- **Canale, agente di risposta, allegato e tutti i contatori di esecuzione sono di sola lettura** qui: `400` se provi a modificarli. Modificali nella campagna.
- **L'avvio** restituisce `400` indirizzandoti all'editor della campagna.
- **Metti in pausa e riprendi** funzionano e agiscono sulla campagna.
- **L'eliminazione** restituisce `400`: elimina invece la campagna e la sua voce nelle Trasmissioni verrà rimossa di conseguenza.
- **La duplicazione** ti fornisce una trasmissione nativa indipendente, che è il metodo supportato per trasferire una campagna comprovata.

---

## Errori

Le richieste non riuscite restituiscono `{"success": false, "error": "<message>"}` con questi stati:

| Stato | Significato |
|---|---|
| `400` | Qualcosa nella richiesta o nello stato della trasmissione non è corretto: un campo mancante, un allegato non valido o un avvio/pausa/ripresa/eliminazione non consentiti nello stato attuale della trasmissione. Il messaggio `error` indica il motivo. |
| `401` | Chiave API mancante o non valida. |
| `403` | Il tuo piano non include l'accesso all'API. |
| `404` | Nessuna trasmissione di questo tipo nel tuo account (o, nella selezione del modello, nessun modello di questo tipo). |
| `429` | Limite di frequenza raggiunto. Riduci la frequenza e riprova. |
| `500` | Qualcosa è andato storto da parte nostra. Riprova dopo una breve attesa. |

---

## Passaggi successivi

- [Guida alle trasmissioni](../broadcasts/broadcasts.md) — il prodotto dietro questi endpoint, inclusi il ritmo e il comportamento di sicurezza
- [API Contatti](contacts.md) — crea l'elenco a cui inviare una trasmissione
- [API Modelli](templates.md) — gestisci i modelli WhatsApp approvati che puoi selezionare
- [API Webhook](webhooks.md) — iscriviti a `Broadcast Started` e `Broadcast Completed` invece di eseguire il polling