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
sideste 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
sideste propriul ID de șablon al Meta — un șir numeric precum"3394843740694756".statusfolosește în continuare valorile din tabelul de mai sus, iarrejection_reasonconț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(receivedsaupending) și untemplate_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_statusestenot_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ă.bodydumneavoastră 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âmpulvariablesdin 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ătheredacă 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
contactIdcare lipsește sau nu se află în contul dumneavoastră returnează403; untemplateIdcare 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
- Autentificare — cele patru modalități de autentificare a unei cereri.
- Erori și limite de rată — coduri de stare și limita de 300 cereri/min.
- API Campanii — gestionați campaniile de care sunt atașate șabloanele.