API pentru difuzări #

O difuzare reprezintă o trimitere externă: un public, un mesaj de deschidere, un canal și o programare. Opțional, aceasta numește și agentul AI care gestionează răspunsurile primite. API-ul pentru difuzări vă permite să creați, să stabiliți prețul, să lansați și să monitorizați acele trimiteri din propriul cod, în loc să folosiți tabloul de bord. Pentru produsul în sine, consultați ghidul pentru difuzări.

• URL de bază — https://api.youraiconnector.com/v1
• Autentificare — cheia ta API (vezi Autentificare)
• Erori și paginare — vezi Erori și paginare

Toate exemplele de mai jos arată forma de interogare ?apiKey= în cURL și antetul X-API-Key în JavaScript și Python — oricare dintre ele funcționează pe fiecare endpoint.

În exploratorul API. Fiecare endpoint de pe această pagină se află în specificația OpenAPI publicată, astfel încât puteți naviga prin câmpurile sale exacte și puteți rula cereri live în exploratorul API.

Cum este structurată o trimitere #

Trimiterea unei difuzări presupune patru apeluri, nu unul:

1. Creați difuzarea cu publicul, canalul și programarea sa — aceasta începe ca un Draft.
2. Setați mesajul de deschidere. Pe WhatsApp Business, aceasta înseamnă trimiterea unui șablon spre aprobare (sau alegerea unuia deja aprobat). Pe orice alt canal, acesta este text simplu.
3. Estimați costul dacă doriți să verificați prețul înainte de a cheltui ceva (opțional).
4. Lansați-o. Lansarea efectuează o verificare completă — public, mesaj, aprobarea șablonului, expeditor conectat — și fie începe trimiterea, fie vă spune exact ce lipsește.

Nimic nu este trimis până când nu apelați funcția de lansare.

Obiectul de difuzare #

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

Marcajele temporale sunt returnate sub formă de milisecunde epoch (execution_date, created_at, last_modified_at, …), iar orice referință la contact este returnată ca un șir de cale, cum ar fi contacts/uid_whatsapp_15551234567.

Câmpuri pe care le setați #

Orice trimiteți ca user_id, id, status sau source_campaign_id este ignorat la creare și eliminat la actualizare — starea se modifică doar prin endpoint-urile de lansare, pauză și reluare de mai jos.

Câmpuri menținute de platformă #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, contoarele de lot și contacts (contactele individuale atașate din tabloul de bord, citite ca șiruri de cale). Citiți-le, nu le scrieți.

Stări #

Crearea unei difuzări #

POST /broadcasts — creează o 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"])

Răspuns (201)

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

Listarea difuzărilor #

GET /broadcasts — fiecare difuzare din cont, cele mai noi primele.

Parametri de interogare

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

Răspuns (200)

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

Obținerea unei difuzări #

GET /broadcasts/{broadcastId} — returnează { "success": true, "broadcast": { ... } }. Folosiți-l pentru a interoga o trimitere în curs: total_contacts_sent, unique_contacts_replied, overall_reply_rate și credits_used se actualizează pe măsură ce procesul avansează.

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

O difuzare care nu există în contul dvs. returnează 404.

Actualizarea unei difuzări #

PUT /broadcasts/{broadcastId} — trimiteți doar câmpurile pe care doriți să le modificați. De asemenea, puteți adresa o singură cheie dintr-un obiect imbricat folosind o cale cu punct, de ex. "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 corp gol returnează 400. Două reguli care merită cunoscute:

• opener_media este de tip totul sau nimic. Trimiteți obiectul complet sau null pentru a elimina atașamentul. O cale cu punct către acesta (opener_media.name) este respinsă cu 400, deoarece un atașament actualizat parțial ar descrie un fișier care nu există.
• Starea nu poate fi editată. Folosiți lansare, pauză și reluare.

Mesajul de deschidere #

Fiecare difuzare își poartă mesajul de deschidere în whats_app_template. Ce înseamnă acest lucru depinde de canal:

• WhatsApp Business — trebuie să fie un șablon aprobat de WhatsApp. Folosiți unul dintre cele două endpoint-uri de mai jos.
• Orice alt canal (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — câmpul body al aceluiași element este pur și simplu textul care este trimis. Trimiterea acestuia prin endpoint-ul de mai jos îl stochează și îl marchează ca fiind gata, fără a implica WhatsApp deloc.

Trimiteți un șablon pentru aprobare #

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

Răspuns (200)

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

template_status este ceea ce spune WhatsApp: pending în timp ce este revizuit, approved când este utilizabil, rejected dacă a fost refuzat. Pe un canal care nu este WhatsApp, acesta revine direct ca approved cu template_sid: null — nimic de revizuit.

Lucruri care vă vor opri:

• Trimiterea în timp ce un șablon anterior este încă în curs de revizuire returnează 400. Așteptați mai întâi decizia.
• Editarea unui șablon care este deja aprobat menține versiunea aprobată activă până când cea nouă revine, astfel încât o difuzare în curs nu își pierde niciodată mesajul de deschidere.
• Pe un număr WhatsApp conectat direct prin Meta, o difuzare cu o imagine sau un videoclip atașat nu poate fi trimisă (400) — atașamentele sunt acceptate pe canalul gestionat WhatsApp Business și pe WhatsApp Web.

Folosiți un șablon pe care l-ați aprobat deja #

POST /broadcasts/{broadcastId}/template/select — copiază un șablon deja aprobat din biblioteca de șabloane pe difuzare, deci nu este nimic de așteptat.

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

Răspuns (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"
}

Aprobarea este verificată de partea noastră din înregistrarea din bibliotecă — trimiteți întotdeauna doar ID-ul. Primiți un 400 dacă difuzarea nu este o ciornă WhatsApp, dacă șablonul nu este aprobat, dacă este un șablon de continuare în loc de unul de deschidere sau dacă difuzarea are un atașament (șabloanele din bibliotecă sunt doar text). Un ID de șablon care nu se află în contul dumneavoastră returnează 404.

Estimați costul #

POST /broadcasts/{broadcastId}/estimate-cost — calculează prețul trimiterii înainte de a vă angaja la aceasta. Disponibil pentru difuzările whatsapp și sms; orice alt canal returnează 400. Difuzarea are nevoie de un list_id, deoarece estimarea numără audiența.

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

Răspuns WhatsApp (200) — credite, defalcate pe țara de destinație:

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

Răspuns prin SMS (200) — dolari americani, pe baza prețurilor live Twilio pentru propriul tău cont 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
  }
}

Citește billing_mode înainte de a afișa un număr. Îți indică cine este facturat:

SMS-urile fără credențiale Twilio conectate returnează în continuare numărul de segmente, cu estimatedCostUsd: 0 — nu există prețuri de consultat.

Lansează o difuzare #

POST /broadcasts/{broadcastId}/launch

Lansarea verifică totul mai întâi și abia apoi trece la difuzare. Nu există lansare parțială: fie pornește, fie nu se schimbă nimic și primești o eroare care explică motivul.

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())

Răspuns (200)

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

status este locul unde a ajuns difuzarea:

• Scheduled — execution_date este în viitor.
• Sending — a început acum.
• Pending Approval — șablonul WhatsApp este încă în curs de examinare. Se va trimite automat imediat ce șablonul este aprobat; nu apelați din nou lansarea.

Doar o difuzare Draft (sau o difuzare Pending Approval al cărei șablon a fost aprobat între timp) poate fi lansată — orice altceva returnează 400.

De ce este refuzată o lansare #

Fiecare dintre acestea revine ca 400 cu un mesaj error în limbaj simplu:

Întrerupere și reluare #

POST /broadcasts/{broadcastId}/pause oprește o difuzare Sending sau Scheduled și anulează tot ce se află în coadă.

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

Întreruperea unei difuzări Pending Approval o readuce în starea Draft — nu era nimic programat încă, deci nu există nimic la care să se revină. Orice altă stare returnează 400.

POST /broadcasts/{broadcastId}/resume repornește o difuzare Paused:

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

Răspuns (200)

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

Aceasta revine la Sending sau înapoi la Scheduled dacă execution_date sa este încă în viitor. Doar o difuzare Paused poate fi reluată.

Continuă trimiterea după o pauză cauzată de implicare scăzută #

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

În timp ce o difuzare se trimite în loturi, măsurăm câți oameni au răspuns la fiecare lot înainte de a-l începe pe următorul. Dacă aproape nimeni nu răspunde, difuzarea se întrerupe automat — o trimitere care continuă să insiste în tăcere este cea mai rapidă cale de a obține filtrarea sau blocarea unui număr. Acesta este butonul Continuă oricum din tabloul de bord.

Deoarece rata de răspuns care a cauzat pauza nu se poate schimba în timp ce difuzarea este oprită, o simplă reluare ar fi întreruptă din nou la următoarea verificare. Acest endpoint reprezintă decizia de a continua oricum: înregistrează suprascrierea pentru acea difuzare și elimină pauza în același apel, dacă difuzarea a fost întreruptă din cauza implicării scăzute.

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

Răspuns (200)

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

• resumed: true — difuzarea a fost întreruptă din cauza implicării scăzute și rulează din nou acum; status este starea la care a revenit.
• resumed: false — nu a fost eliminată nicio restricție, suprascrierea este pur și simplu înregistrată pentru verificări viitoare. Aceasta este ceea ce primești dacă difuzarea nu a fost niciodată întreruptă sau a fost întreruptă dintr-un alt motiv (ai întrerupt-o manual, a fost atinsă o limită de trimitere sau prea multe trimiteri au generat erori). Acele pauze nu sunt eliminate aici — reia difuzarea singur după ce ai rezolvat cauza.

Suprascrierea se aplică doar acestei difuzări. Nu este o setare a contului și este sigur să fie apelată de două ori.

Duplică o difuzare #

POST /broadcasts/{broadcastId}/duplicate — copiază audiența, mesajul și setările într-o nouă Draft. Tot ce ține de rularea anterioară (contori, loturi, programare, statistici de răspuns) pornește de la 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" }'

Răspuns (201)

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

O copie nu moștenește niciodată o aprobare WhatsApp activă: pe o copie WhatsApp, șablonul vine necesitând confirmarea ta, iar pe o copie către un alt canal, acesta este eliminat și textul devine deschiderea simplă. Copierea către SMS elimină, de asemenea, orice atașament, deoarece SMS-ul nu poate trimite unul.

Șterge o difuzare #

DELETE /broadcasts/{broadcastId}

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

O difuzare Sending sau Scheduled este refuzată cu 400 — întrerupeți-o mai întâi.

Difuzări care oglindesc o campanie clasică #

Campaniile clasice care trimit mesaje apar, de asemenea, în Difuzări, iar API-ul le returnează alături de difuzările native (acestea poartă un source_campaign_id). Acestea se comportă puțin diferit, deoarece campania rămâne responsabilă:

• Editarea audienței, a mesajului sau a programării funcționează și este aplicată campaniei.
• Canalul, agentul de răspuns, atașamentul și toți contorii de rulare sunt doar în citire aici — 400 dacă încercați să îi modificați. Modificați-i în cadrul campaniei.
• Lansarea returnează 400, direcționându-vă către editorul campaniei.
• Întreruperea și reluarea funcționează și acționează asupra campaniei.
• Ștergerea returnează 400 — ștergeți campania în schimb, iar intrarea sa din Difuzări va fi eliminată odată cu aceasta.
• Duplicarea vă oferă o difuzare nativă independentă, care este metoda acceptată pentru a transfera o campanie dovedită.

Erori #

Cererile eșuate returnează {"success": false, "error": "<message>"} cu următoarele stări:

Pașii următori #

• Ghidul Difuzărilor — produsul din spatele acestor endpoint-uri, inclusiv ritmul și comportamentul de siguranță
• API Contacte — construiți lista către care trimite o difuzare
• API Șabloane — gestionați șabloanele WhatsApp aprobate pe care le puteți selecta
• API Webhooks — abonați-vă la Broadcast Started și Broadcast Completed în loc să interogați