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.

• URL di base — https://api.youraiconnector.com/v1
• Autenticazione — la tua chiave API (vedi Autenticazione)
• Errori e paginazione — vedi Errori e paginazione

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.

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 #

{
  "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 #

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 #

Crea una trasmissione #

POST /broadcasts — crea una Draft.

cURL

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

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

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)

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

Elenca trasmissioni #

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

Parametri di query

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

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

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)

{ "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. |

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".

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

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, pausa e riprendi.

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

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)

{ "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 nella trasmissione, quindi non c’è nulla da attendere.

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)

{
  "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.

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:

{
  "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:

{
  "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:

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

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

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

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

Risposta (200)

{ "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:

Metti in pausa e riprendi #

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

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:

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

Risposta (200)

{ "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 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.

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

Risposta (200)

{ "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.

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)

{ "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}

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:

Passaggi successivi #

• Guida alle trasmissioni — il prodotto dietro questi endpoint, inclusi il ritmo e il comportamento di sicurezza
• API Contatti — crea l’elenco a cui inviare una trasmissione
• API Modelli — gestisci i modelli WhatsApp approvati che puoi selezionare
• API Webhook — iscriviti a Broadcast Started e Broadcast Completed invece di eseguire il polling