Your AI Connector Docs

API pentru șabloane WhatsApp

Șabloanele de mesaje WhatsApp sunt mesaje predefinite care au fost aprobate pentru a fi trimise în afara ferestrei normale de conversație de 24 de ore — de exemplu, un mesaj de bun venit, un memento pentru programare sau un mesaj de reangajare. Această API vă permite să listați, să creați, să editați, să trimiteți, să verificați, să ștergeți și să expediați șabloane în mod programatic.

Toate căile de mai jos sunt relative la URL-ul de bază al API-ului:

https://api.youraiconnector.com/v1

Fiecare cerere trebuie să fie autentificată. Consultați Autentificare pentru cele patru metode acceptate. Exemplele de pe această pagină utilizează antetul X-API-Key (și o formă de parametru de interogare pentru cURL).

Notă: Șabloanele rulează pe canalul WhatsApp Business API, deci această parte a API-ului necesită atât acces API, cât și un plan care include canale WhatsApp. Fără acestea, solicitările sunt respinse cu un 403.


Lucrul cu sub-conturi (agenții)


Stări de aprobare

Deoarece mesajele trimise în afara unei conversații deschise trebuie mai întâi revizuite de WhatsApp, fiecare șablon poartă o stare de aprobare status:

Status Semnificație
draft Creat sau salvat, dar nu a fost încă trimis pentru revizuire. Îl puteți edita în continuare.
received Trimis și acceptat în coada de revizuire.
pending În curs de revizuire.
approved Aprobat pentru trimitere.
rejected Respins. Câmpul rejection_reason explică motivul; corectați-l, apoi trimiteți din nou.

Doar șabloanele draft și rejected pot fi editate sau (re)trimise. Odată ce un șablon este approved, acesta este blocat — creați unul nou dacă aveți nevoie de modificări.

Aprobare automată: Unele canale nu necesită o etapă de revizuire externă. Șabloanele create sau trimise pentru o campanie pe un astfel de canal sunt stocate imediat ca approved, fără un ID de conținut (sid).


Șabloane pentru conturile conectate la Meta

Aceste endpoint-uri funcționează în același mod indiferent de conexiunea WhatsApp pe care o utilizează contul tău, însă ceea ce se întâmplă în spate diferă:

  • Pe o conexiune WhatsApp gestionată, șabloanele sunt înregistrate la furnizorul de mesagerie, iar sid este ID-ul de conținut al furnizorului (HXXXXXXXX…).
  • Pe un cont al cărui număr rulează pe propriul său cont WhatsApp Business (oricare dintre opțiunile de conexiune Meta), șabloanele sunt create și revizuite în acel cont WhatsApp Business, iar sid este propriul ID de șablon al Meta — un șir numeric precum "3394843740694756". status folosește în continuare valorile din tabelul de mai sus, iar rejection_reason conține în continuare explicația Meta.

Există două endpoint-uri suplimentare pentru acest lucru: unul pentru a întreba pe ce conexiune te afli și unul pentru a reconcilia lista ta de șabloane cu contul tău WhatsApp Business. Șabloanele care există deja în contul WhatsApp Business sunt importate în biblioteca ta prin sincronizare, astfel încât un GET /whatsapp-templates ulterior le va lista ca pe oricare alt șablon.

Verifică pe ce conexiune rulează șabloanele

GET /whatsapp-templates/provider

Câmp Descriere
provider twilio când șabloanele sunt înregistrate la furnizorul de mesagerie gestionat, meta când acestea se află în propriul tău cont WhatsApp Business.
lane Ce conexiune Meta este utilizată — meta_cloud_api (propria ta aplicație Meta) sau meta_embedded (conectată prin aplicația noastră Meta). null pe o conexiune gestionată.
waba_id Contul WhatsApp Business în care sunt create șabloanele sau null.
templates_enabled false când conexiunea Meta nu este încă finalizată (nu există niciun cont WhatsApp Business sau token de acces stocat). Crearea sau trimiterea șabloanelor eșuează cu un 400 până când acest lucru este rezolvat.

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/provider", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}

Sincronizează șabloanele de la Meta

Actualizează starea de aprobare a fiecărui șablon care se află în contul tău WhatsApp Business și importă orice șablon care există acolo, dar nu se află încă în biblioteca ta. Poate fi apelat în siguranță oricât de des dorești. Pe o conexiune gestionată nu există nimic de sincronizat, așa că apelul nu face nimic și raportează pur și simplu câte șabloane ai.

POST /whatsapp-templates/meta-sync

Câmp Descriere
imported Șabloane găsite în contul WhatsApp Business care au fost adăugate în biblioteca ta prin acest apel.
updated Șabloane existente a căror stare sau detalii s-au modificat.
total Șabloane aflate în biblioteca ta după sincronizare.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}

Comunicarea directă cu Meta (avansat)

Dacă ai nevoie de ceva ce endpoint-urile de mai sus nu expun — anteturi de șablon, subsoluri, butoane sau un șablon creat complet manual — /v1/meta-templates transmite cererea ta direct către API-ul de șabloane al Meta, fără a stoca nimic în biblioteca ta de șabloane. Funcționează doar pe conturile al căror număr rulează pe propriul lor cont WhatsApp Business; pe o conexiune gestionată, fiecare apel returnează 400, solicitându-ți să conectezi mai întâi o aplicație Meta.

Endpoint Ce face
GET /meta-templates Listează șabloanele din contul tău WhatsApp Business cu cea mai recentă stare a acestora. Adaugă ?name= pentru a filtra după un nume exact de șablon. Returnează { "success": true, "templates": [...] }.
POST /meta-templates Creează un șablon și îl trimite spre revizuire către Meta într-un singur pas. Necesită name, language și body (sau un tablou components complet în loc de body). Opțional: variables (tablou de șiruri), category (MARKETING, UTILITY sau AUTHENTICATION), header, footer, buttons. Returnează 201 cu { "success": true, "template": {...} }.
DELETE /meta-templates/{name} Șterge șablonul după numele său Meta — fiecare limbă a acestuia. Adaugă ?hsm_id= cu ID-ul de șablon al Meta pentru a elimina o singură limbă. Returnează { "success": true, "name": "..." }.

Un șablon refuzat de Meta returnează 400 cu explicația Meta în error.


Listarea șabloanelor

Returnează toate șabloanele din contul dvs., cu un rezumat succint al fiecăruia.

GET /whatsapp-templates

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}

Obținerea unui șablon

Returnează detaliile complete ale unui singur șablon, inclusiv variabilele, starea și marcajele temporale ale acestuia.

GET /whatsapp-templates/{templateId}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}

Un șablon care nu există în contul dvs. returnează 404 cu { "success": false, "error": "Template not found" }.


Crearea unui șablon

Creează un șablon pentru mesajul de deschidere al unei campanii și îl trimite spre aprobare într-un singur pas.

POST /whatsapp-templates

Câmp Obligatoriu Descriere
campaign_id Da Campania de care aparține șablonul.
name Da Un nume pentru șablon.
language Da Codul limbii, de exemplu en, es, de, pt_BR, zh_CN.
body Da Textul mesajului, de până la 1024 de caractere.
variables Nu Listă ordonată de nume de variabile utilizate în corp.

Substituenții de variabile pot fi scriși ca {{first_name}}, {first_name} sau [first_name] — toți sunt normalizați la forma cu acolade duble.

Rezultatul depinde de canalele campaniei:

  • Campanie WhatsApp Business API: conținutul este trimis pentru revizuirea WhatsApp. Răspunsul conține campaign_status (received sau pending) și un template_sid.
  • Un canal fără etapă de revizuire externă: șablonul este stocat și aprobat automat (campaign_status: "approved", template_sid: null).
  • Fără canal WhatsApp în campanie: nu se creează nimic și campaign_status este not_applicable.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

Răspuns (trimis spre revizuire)

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Crearea unui șablon independent

Creează un șablon în biblioteca dvs. de șabloane fără a-l lega de mesajul de deschidere al unei campanii. Acesta este pasul de creare din ciclul de viață pe care îl urmează restul acestei pagini: creați-l aici, editați-l, trimiteți-l spre revizuire, verificați-i starea și ștergeți-l când nu mai aveți nevoie de el.

POST /whatsapp-templates/docs

Câmp Obligatoriu Descriere
name Da Un nume pentru șablon.
language Da Codul limbii, de exemplu en, es, de, pt_BR, zh_CN.
body Da Textul mesajului, până la 1024 de caractere.
variables Nu Listă ordonată de nume de variabile utilizate în corp.
status Nu draft (implicit) îl stochează fără a-l trimite; submitted îl pune direct în coada de așteptare pentru revizuirea WhatsApp.
type Nu general (implicit) sau smart_followup.
category Nu marketing, utility, authentication sau authentication-international.
campaign_id Nu Leagă șablonul de una dintre campaniile dvs.

Șabloane de autentificare (cod unic). WhatsApp nu acceptă șabloane de autentificare cu text liber: corpul mesajului este prestabilit de WhatsApp, iar șablonul trebuie să conțină un buton de „copiere cod”. Când creați un șablon cu category: "authentication", noi îl trimitem în acea formă fixă pentru dumneavoastră. body dumneavoastră este păstrat ca previzualizare afișată în aplicație, dar textul pe care îl primește contactul este formularea proprie WhatsApp (codul, un memento de securitate și o notă de expirare de 10 minute). Declarați exact o variabilă, de exemplu ["code"], și transmiteți codul când trimiteți (consultați câmpul variables din Trimiteți un șablon către un contact). Codul trebuie să aibă mai puțin de 15 caractere.

Ce metodă de creare ar trebui să folosesc? Folosiți-o pe aceasta atunci când doriți un șablon pe care să îl puteți edita și trimite singur. Folosiți POST /whatsapp-templates (de mai sus) atunci când doriți să setați mesajul de deschidere al unei campanii — aceasta necesită campaign_id și scrie direct în campanie.

Un șablon creat ca submitted este trimis pentru revizuirea WhatsApp în fundal, așa că verificați endpoint-ul de stare pentru rezultat în loc să vă așteptați la acesta în răspuns.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}

Un name, language sau body lipsă, o limbă neacceptată, un status altul decât draft sau submitted, un type sau category necunoscut sau un corp de text de peste 1024 de caractere returnează 400 cu un error explicativ. Un campaign_id care nu este una dintre campaniile dvs. returnează 404.


Actualizarea unui șablon

Editează un șablon care nu a fost încă aprobat. Doar șabloanele cu starea draft sau rejected pot fi editate. Furnizați orice combinație de name, body, language și variables — doar câmpurile pe care le trimiteți vor fi modificate.

PUT /whatsapp-templates/{templateId}

Editarea nu retrimite șablonul pentru revizuire. Folosiți endpoint-ul de trimitere ulterior.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "template_id": "template_abc123"
}

Încercarea de a edita un șablon care este deja approved (sau care nu poate fi editat din alte motive), trimiterea fără câmpuri sau trimiterea unei valori invalide returnează 400 cu un error explicativ.


Trimiterea unui șablon pentru aprobare

Trimite un șablon draft sau rejected pentru revizuire. Șabloanele de pe un canal care nu necesită revizuire externă sunt aprobate imediat; toate celelalte sunt trimise către WhatsApp, iar status returnat (de obicei received sau pending) este stocat în șablon.

POST /whatsapp-templates/{templateId}/submit

Șabloanele de follow-up trebuie să declare și să utilizeze variabilele necesare înainte de a putea fi trimise: un substituent pentru prenume, plus un substituent pentru context personal în cazul șabloanelor de follow-up inteligente.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Verificarea stării aprobării

Un endpoint ușor pentru interogarea stării curente a unui șablon. Starea este citită din înregistrarea stocată, care este actualizată periodic în fundal, astfel încât o aprobare sau o respingere foarte recentă poate dura puțin până când apare.

GET /whatsapp-templates/{templateId}/status

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}

Ștergerea unui șablon

Elimină înregistrarea șablonului din contul dumneavoastră.

DELETE /whatsapp-templates/{templateId}

Important: Pe o conexiune gestionată, este eliminată doar înregistrarea stocată — conținutul pe care WhatsApp l-a aprobat deja poate rămâne înregistrat la furnizorul de mesagerie. Într-un cont care rulează pe propriul său WhatsApp Business Account, șablonul este șters și din acel cont. Oricum ar fi, dacă o campanie încă folosește acest șablon, redirecționați acea campanie către un alt șablon înainte de ștergere, altfel trimiterile care se bazează pe acesta vor eșua.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}

Trimite un șablon către un contact

Trimite un șablon aprobat către un contact, chiar și atunci când nu există o conversație deschisă — acest lucru redeschide sesiunea de chat. Puteți viza contactul prin contactId sau prin phoneNumber și puteți alege șablonul prin whatsappTemplateId sau prin templateName.

POST /whatsapp-templates/send

Câmp Obligatoriu Descriere
contactId Unul dintre cele două ID-ul contactului.
phoneNumber Unul dintre cele două Numărul de telefon al contactului (cu prefixul țării, fără spații). Căutat sau creat dacă este necesar.
whatsappTemplateId Unul dintre cele două ID-ul șablonului.
templateName Unul dintre cele două Numele șablonului, așa cum apare în aplicație.
firstName Nu Folosit pentru a completa un contact nou creat.
lastName Nu Folosit pentru a completa un contact nou creat.
email Nu Folosit pentru a completa un contact nou creat.
variables Nu Valori explicite pentru variabilele șablonului, identificate prin numele variabilei, de exemplu { "code": "482913" }. O valoare oferită aici prevalează asupra câmpurilor contactului pentru acea variabilă; variabilele pe care le omiteți sunt totuși completate din contact, așa cum este descris mai jos. Acesta este modul în care transmiteți un cod unic către un șablon de autentificare.

Corpul șablonului acceptă substituția avansată a variabilelor:

  • Variabile de bază: {{first_name}}, {{email}}, {{company}}
  • Valori implicite: {{first_name|there}} afișează there dacă câmpul este gol
  • Transformări: {{company|uppercase}}, {{name|lowercase}}, {{name|capitalize}}
  • Combinate: {{company|Your Company|uppercase}}

Credite: Trimiterea unui șablon consumă credite. Costul exact depinde de țara destinatarului și de categoria șablonului.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

O cerere căreia îi lipsește atât un identificator de contact, cât și ambii identificatori de șablon returnează 400. Dacă contului dumneavoastră îi lipsesc credențialele de mesagerie necesare pentru trimitere, răspunsul este 403.


Crearea sau actualizarea șablonului activ al unei campanii

O a doua pereche de endpoint-uri pentru șablonul de deschidere al unei campanii, delimitate prin cale în loc de un campaign_id în corp. Acestea sunt cele de utilizat pentru o campanie care este deja activă: spre deosebire de Crearea unui șablon de mai sus, actualizarea aici retrimite și ciornele de follow-up ale campaniei pentru revizuire, astfel încât șablonul de deschidere și mesajele sale de follow-up să rămână sincronizate.

POST /whatsapp-templates/campaign/{campaignId} creează șablonul de deschidere al campaniei. PUT /whatsapp-templates/campaign/{campaignId} îl editează — campania trebuie să aibă deja un șablon, altfel va fi returnat 400.

Câmp Obligatoriu Descriere
name Da Un nume pentru șablon.
language Da Codul limbii, de exemplu en, es, de, pt_BR, zh_CN.
body Da Textul mesajului, până la 1024 de caractere.
variables Da Listă ordonată de nume de variabile utilizate în corp. Transmiteți un tablou gol dacă șablonul nu utilizează niciuna.

cURL (creare)

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}

Pentru a edita, schimbați metoda în PUT și folosiți aceleași câmpuri — acest lucru retrimite șablonul de deschidere (și ciornele de follow-up ale campaniei, în cazul unei campanii WhatsApp API) pentru revizuire.

O campanie care nu aparține contului dumneavoastră returnează 404; o campanie care aparține unui alt cont pentru care nu sunteți autorizat returnează 403. Editarea unei campanii fără un șablon existent returnează 400.


Trimiterea unui șablon către un contact existent

O alternativă mai simplă, delimitată prin cale, la Trimiterea unui șablon către un contact de mai sus: atât șablonul, cât și contactul trebuie să existe deja — nimic nu este căutat după nume sau creat pe loc.

POST /whatsapp-templates/{templateId}/send-to-contact

Câmp Obligatoriu Descriere
contactId Da ID-ul contactului. Trebuie să aparțină contului dumneavoastră.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()

Răspuns

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

Credite: Trimiterea consumă credite, tarifate la fel ca endpoint-ul de mai sus. Un contactId care lipsește sau nu se află în contul dumneavoastră returnează 403; un templateId care nu există returnează 404.


Trimiterea în masă a unui șablon

Trimiteți un șablon către mai multe contacte într-un singur apel, cu o previzualizare a costurilor pe care o puteți afișa înainte de confirmare.

Estimați costul în prealabil

Returnează costul trimiterii, defalcat pe țara de destinație, fără a trimite nimic sau a consuma credite. Prețul șablonului este per țară de destinație, deci acesta trebuie calculat pe server în raport cu contactele reale, în loc să fie estimat pe partea de client.

POST /whatsapp-templates/{templateId}/estimate-bulk-cost

Câmp Obligatoriu Descriere
contactIds Da Contacte pentru calcularea prețului, până la 500 per apel. Duplicatele sunt numărate o singură dată.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

Răspuns

{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}

skippedContacts numără ID-urile care au lipsit, nu au fost ale tale sau nu aveau un număr de telefon — estimarea acoperă doar restul, deci o valoare diferită de zero înseamnă că trimiterea reală va ajunge la mai puține contacte decât ai selectat.

Trimite lotul

Trimite șablonul către fiecare contact din listă, rezolvând orice variabile inteligente per contact și taxând credite per trimitere.

POST /whatsapp-templates/{templateId}/bulk-send

Câmp Obligatoriu Descriere
contactIds Da Contacte către care se trimite, până la 5000 per apel.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

Răspuns

{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}

Un contact care eșuează (nu a fost găsit, nu este în contul tău sau o eroare de trimitere) este omis și numărat în failed în loc să oprească lotul. Un contactIds gol, mai mult de 5000 de ID-uri la o trimitere (500 la o estimare) sau un templateId lipsă returnează 400.


Reîncearcă un mesaj eșuat

Două endpoint-uri pentru retrimiterea unui mesaj care a eșuat, fără a crea o înregistrare nouă de mesaj sau a consuma din nou credite.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template reîncearcă în mod specific un mesaj de tip șablon eșuat — acesta rezolvă din nou conținutul șablonului din campanie dacă mesajul eșuat nu îl conține deja. Doar mesajele cu starea failed și tipul template pot fi reîncercate în acest mod.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry este agnostic față de canal și funcționează pentru orice mesaj eșuat care nu este de tip șablon (de exemplu, WhatsApp Web), trimițând mesajul pe calea corectă de trimitere în funcție de canalul acestuia. Acceptă starea failed, failed_connection, limit_exceeded sau queued_retry.

Niciun endpoint nu necesită un corp al cererii (request body).

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "data": "Message retry initiated successfully"
}

Pentru versiunea agnostică față de canal, schimbă calea către .../msg_abc789/retry. Un mesaj a cărui stare nu este eligibilă pentru reîncercare sau (pe endpoint-ul de șablon) care nu este un mesaj de tip șablon, returnează 400. Un contact sau un mesaj lipsă returnează 404.


Profil WhatsApp Business

Gestionează profilul WhatsApp Business (despre, adresă, descriere, e-mail, site-uri web, categoria afacerii și logo) afișat contactelor pe WhatsApp. Funcționează atât pe o conexiune gestionată, cât și pe un cont care rulează propriul său cont WhatsApp Business.

Salvarea profilului

PUT /whatsapp-templates/profile

Câmp Obligatoriu Descriere
phoneNumber Da Numărul WhatsApp căruia îi aparține acest profil. Trebuie să fie conectat la contul tău.
about Nu Text scurt “Despre” afișat pe profil.
address Nu Adresa afacerii.
description Nu Descriere mai lungă a afacerii.
email Nu E-mail de contact afișat pe profil.
websites Nu Matrice de URL-uri ale site-urilor web. Fiecare trebuie să fie un URL valid.
vertical Nu Categoria afacerii, de exemplu Retail sau Professional Services.
profilePictureHandle Nu Identificatorul returnat de punctul final de încărcare a imaginii de mai jos, pentru a seta fotografia de profil.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}

Un phoneNumber lipsă, un URL de site web invalid sau un phoneNumber neconectat la contul tău returnează 400 sau 404.

Încărcarea unei fotografii de profil

Descarcă o imagine de la un URL furnizat de tine și o încarcă pe WhatsApp, returnând un identificator. Transmite acel identificator ca profilePictureHandle în apelul de salvare a profilului de mai sus pentru a o seta ca fotografie — acest punct final doar încarcă imaginea, nu o setează automat.

POST /whatsapp-templates/profile/picture

Câmp Obligatoriu Descriere
phoneNumber Da Numărul WhatsApp căruia îi aparține acest profil.
fileUrl Da Un URL accesibil public către imaginea de încărcat.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "data": "1234567890123456"
}

data este identificatorul imaginii încărcate. Un phoneNumber sau fileUrl lipsă, sau un phoneNumber fără un token de acces WhatsApp în fișier, returnează 400; un fileUrl inaccesibil sau invalid returnează o eroare care descrie motivul eșecului descărcării.


Verificarea stării unui expeditor

Interoghează (și reîmprospătează) starea de trimitere în timp real a unui număr WhatsApp conectat la furnizorul de mesagerie. Util pentru a confirma că un număr este într-adevăr capabil să trimită mesaje înainte de a te baza pe el.

GET /whatsapp-templates/sender-status/{phoneNumber}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "data": "ONLINE"
}

data este unul dintre ONLINE (trimite normal), PENDING (încă în curs de verificare) sau DELETED (furnizorul nu mai recunoaște acest expeditor — reconectează numărul). Un phoneNumber fără informații de afaceri WhatsApp în fișier returnează 404.


Generați șabloane de follow-up cu AI

Platforma poate scrie pentru dvs. șabloanele de follow-up pe WhatsApp ale unei campanii — mesajele de reamintire trimise atunci când o conversație devine inactivă — pe baza instrucțiunilor și obiectivului campaniei. Există un endpoint de tip job care rulează în fundal, plus trei endpoint-uri mai vechi păstrate pentru integrările existente. Toate utilizează credite AI.

Inițierea unui job de generare

POST /campaigns/{campaignId}/template-generation

Câmp Obligatoriu Descriere
type Nu all (implicit) scrie întregul set de follow-up. cold_only scrie doar mesajele pentru contactele care nu au răspuns niciodată.

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "all" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
data = res.json()

Răspuns (202)

{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }

Apelul returnează un răspuns imediat ce jobul este pus în coadă. Citiți campania (GET /campaigns/{campaignId}, consultați API-ul pentru Campanii) și monitorizați obiectul template_generation_status al acesteia până când procesul se finalizează:

Câmp Descriere
status processing în timp ce jobul rulează, apoi completed sau failed.
progress De la 0 la 100.
current_template, total_templates Câte șabloane au fost scrise până acum, din totalul pe care jobul îl va scrie — 11 pentru o campanie de ieșire sau combinată, 9 în caz contrar.
error Motivul pentru care un job failed s-a oprit, de exemplu, credite insuficiente.
started_at, completed_at Când a început și s-a terminat jobul.

Șabloanele generate ajung în campanie ca oricare altele, deci apar în Listare șabloane și trec în continuare prin aprobarea WhatsApp înainte de a putea fi trimise. Un 400 înseamnă că type a fost altceva decât all sau cold_only; un 404 înseamnă că respectiva campanie nu există sau aparține unui alt cont.

Agenții au un echivalent al acestui apel, POST /agents/{agentId}/template-generation, care scrie mesajele de follow-up pentru un Agent și se finalizează în timpul apelului în cazul obișnuit — consultați Generare mesaje de follow-up în API-ul pentru Agenți AI.

Endpoint-urile de generare mai vechi

Trei endpoint-uri anterioare fac aceeași treabă și sunt păstrate pentru ca integrările existente să continue să funcționeze. Codul nou ar trebui să utilizeze endpoint-ul de tip job de mai sus.

Endpoint Ce face
POST /whatsapp-templates/campaign/{campaignId}/generate-async Pornește generarea de follow-up pentru campanie în fundal și returnează 202 cu { "success": true, "data": { "result": "success", "message": "..." } }. Creditele sunt taxate în avans (se omite în cazul unui cont care își aduce propria cheie AI), iar template_generation_status al campaniei raportează progresul exact ca mai sus.
POST /whatsapp-templates/campaign/{campaignId}/generate-followups Generează toate cele nouă șabloane de follow-up în timpul apelului — pentru o campanie creată înainte de existența follow-up-urilor automate, sau una care necesită rescrierea acestora — și returnează 200 cu templatesGenerated în interiorul data.
POST /whatsapp-templates/agent/{agentId}/generate-followups Aceeași generare sincronă adresată de Agent. Răspunsul adaugă agent_id, campaign_id și target: "campaign" când șabloanele au fost scrise în campania Agentului, "agent" (cu campaign_id: null) când Agentul nu are nicio campanie și acestea au fost stocate pe Agentul însuși. Un Agent lipsă sau străin reprezintă un 404.

Toate cele trei necesită follow-up-uri automate pe cont și suficiente credite — un 400 indică ce lipsește — iar perechea adresată campaniei returnează 403 atunci când campania aparține unui alt cont.


Erori API pentru șabloane

Endpoint-urile pentru șabloane returnează plicul standard de eroare:

{
  "success": false,
  "error": "Template not found"
}

Un 404 pe aceste endpoint-uri înseamnă de obicei că resursa nu a fost găsită — fie nu există, fie aparține unui alt cont. Câteva endpoint-uri (creare/actualizare la nivel de campanie și trimiteri către un contact existent) returnează 403 în schimb atunci când campania sau contactul aparține altcuiva, în loc să nu existe deloc. Unele endpoint-uri includ, de asemenea, un câmp error_code care oglindește starea HTTP. Codurile partajate pe care le poate returna orice endpoint — 400, 401, 403 (planul tău nu include acces API), 429 (limită de rată) și 500 — sunt listate cu instrucțiuni de reîncercare în Erori și Paginare.


Pașii următori