WhatsApp Template API

API pentru dezvoltatori

Trimiteți șabloane WhatsApp aprobate din propriile sisteme cu un singur apel API; conversația continuă apoi în MonoChat.

• WhatsApp
• REST API
• Doar API

Instalați din MonoStoreVedeți-o pe monochat.ai

Prezentare generală

WhatsApp Template API permite CRM-ului, ERP-ului, site-ului de comerț electronic sau oricărui backend să trimită unui client, prin MonoChat, un mesaj șablon WhatsApp aprobat. O singură cerere indică numărul WhatsApp de pe care se trimite, numărul de telefon al clientului, șablonul și variabilele sale.

Când clientul răspunde, conversația ajunge în inbox-ul dvs. MonoChat ca oricare alta. Aplicația nu are ecrane proprii: totul se petrece prin trei endpoint-uri API.

Puncte forte

• Un singur apel API. Trimiteți un șablon după nume și limbă, cu variabilele de antet, corp, buton și carusel completate din datele dvs.
• Direct în chat. Fiecare trimitere returnează id-ul conversației și un link direct către ea în MonoChat.
• Clienții noi sunt bineveniți. Dacă numărul de telefon nu este încă client, clientul este creat cu numele pe care îl trimiteți.

Instalare și configurare

1. Conectați numărul dvs. WhatsApp Business la MonoChat și asigurați-vă că este verificat și are șabloane aprobate de Meta.
2. Instalați WhatsApp Template API din Setări › MonoStore › Aplicații sau deschideți linkul de instalare app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Dacă nu aveți un cont MonoChat, linkul vă permite să vă înregistrați mai întâi și instalează aplicația pentru dvs.
3. Creați un token API în Profil › Token-uri API. Token-ul este afișat o singură dată, așa că copiați-l imediat.
4. Apelați template/list.js pentru a vedea șabloanele aprobate și variabilele lor.
5. Apelați template/send.js cu numărul clientului și valorile variabilelor pentru a trimite primul dvs. șablon.

notă

• Fiecare mesaj este facturat ca orice mesaj șablon trimis din MonoChat.
• URL-urile media trebuie să rămână accesibile până când WhatsApp preia fișierul.
• Trimiteți clienților care au fost de acord să primească mesaje de la dvs.: WhatsApp poate limita numerele ale căror mesaje sunt blocate sau raportate.

Funcționalități

Listare șabloane

Șabloanele aprobate ale unui număr WhatsApp, cu limba, categoria, starea și variabilele lor, ca sistemul dvs. să știe ce poate trimite.

Trimitere șablon

După numele și limba șablonului, cu variabilele de antet, corp, buton și carusel. O valoare lipsă oprește trimiterea, deci nimic completat pe jumătate nu ajunge la client.

Atribuire unui agent

Dați e-mailul unui agent și conversația se deschide pe numele lui.

Antete media

Obțineți date de încărcare cu valabilitate scurtă, puneți o imagine, un videoclip sau un document în spațiul de stocare MonoChat și folosiți URL-ul său ca antet al șablonului.

Link către conversație

Fiecare trimitere returnează id-ul sesiunii, id-ul mesajului și un link care deschide conversația în MonoChat.

Erori clare

Un apel eșuat spune ce a mers prost, de exemplu „Channel not found” sau „Variable missing”.

Înainte de a începe

• Numărul dvs. WhatsApp Business este conectat la MonoChat și verificat. Consultați Canale.
• Șabloanele pe care doriți să le trimiteți sunt aprobate de Meta. Șabloanele sunt modul în care scrieți primii sau ajungeți la un client în afara ferestrei de 24 de ore. Consultați Mesaje șablon.
• Aveți un token API din Profil › Token-uri API. Consultați Token-uri API.
• Cunoașteți tenant slug-ul dvs.: partea de după /tenants/ din adresa dvs. MonoChat. În https://app.monochat.ai/tenants/mybusiness, slug-ul este mybusiness.

Referință API

Aplicația nu are ecrane proprii. Totul se petrece prin trei endpoint-uri, fiecare un POST cu corp JSON:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Endpoint	Ce face
template/list.js	Listează șabloanele unuia dintre numerele dvs. WhatsApp, cu variabilele lor.
template/send.js	Trimite un șablon unui client și returnează un link către conversație.
upload/get-token.js	Oferă date de încărcare cu valabilitate scurtă pentru o imagine, un videoclip sau un document de antet.

Numerele de telefon se scriu întotdeauna cu prefixul de țară și fără +, de exemplu 905334445566. Un apel reușit răspunde cu 200 și cu datele endpoint-ului în result.

1. Listare șabloane

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Listează toate șabloanele numărului WhatsApp Business indicat: nume, cod de limbă, categorie, componente (antet, corp, subsol, butoane), tipuri de variabile și starea aprobării.

Câmp	Obligatoriu	Descriere
phoneNumber	da	Numărul dvs. WhatsApp Business din MonoChat, cu prefix de țară, fără +.
options	nu	Paginare și filtre, de exemplu { "pagination": { "currentPage": 1, "pageItems": 50 } }.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Răspuns (prescurtat):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Cum se citește:

• name: numele de sistem cu care trimiteți șablonul.
• languageCode: limba în care se trimite.
• category: categoria WhatsApp (MARKETING, UTILITY, AUTHENTICATION).
• components: părțile din care este alcătuit șablonul.

Componentă	Conținut	Descriere
HEADER	IMAGE, VIDEO, DOCUMENT sau text	Pentru media se indică format; variabilele apar în variables.
BODY	Text cu variabile	Corpul mesajului, cu substituenți precum {{1}}, {{2}}.
FOOTER	Text	De obicei nu are variabile.
BUTTONS	URL, răspuns rapid…	Textele butoanelor și variabilele lor, dacă există.

Șablonul de exemplu de mai sus are nevoie de o imagine pentru antet și de două texte pentru corp (numele clientului și numele produsului). Subsolul este fix („Teşekkürler”) și nu există butoane.

2. Trimitere șablon

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Trimite un șablon aprobat unui client. Dacă numărul de telefon nu este încă client, clientul este creat; conversația este deschisă (sau refolosită), iar șablonul este trimis în ea.

Câmp	Obligatoriu	Descriere
phoneNumber	da	Numărul WhatsApp Business de pe care se trimite. Trebuie să fie conectat la MonoChat și verificat.
templateMessageName	da	name-ul șablonului, exact așa cum îl returnează lista.
languageCode	da	Limba șablonului, așa cum o returnează lista (de exemplu tr-TR).
customerPhoneNumber	da	Numărul WhatsApp al clientului.
variables	când șablonul are variabile	Valorile variabilelor șablonului (vezi mai jos).
customerFirstName, customerLastName	nu	Folosite când clientul este nou în MonoChat.
agentEmailAddress	nu	Atribuie conversația agentului cu acest e-mail.

Variabile. Fiecare element din array-ul variables are un type și o listă de parameters, date în ordinea substituenților șablonului:

type	parameters
HEADER	Variabila de text a antetului sau URL-ul public al imaginii, videoclipului ori documentului din antet.
BODY	{{1}}, {{2}}, … ale corpului, în ordine.
BUTTONS	Câte o valoare pentru fiecare buton care are o variabilă (de exemplu partea dinamică a unui buton URL sau un cod de cupon), în ordinea butoanelor.
CAROUSEL	În loc de parameters, un array cards cu câte o intrare pentru fiecare card din carusel, fiecare cu propriile components.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

O valoare lipsă oprește trimiterea cu Variable missing, deci nimic completat pe jumătate nu ajunge la client. FOOTER are rar variabile.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Răspuns:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

• url: deschide conversația în MonoChat, pentru persoanele autentificate și care au voie să o vadă.
• sessionId: id-ul conversației.
• messageId: id-ul mesajului în MonoChat. Starea livrării și a citirii apare în chat ca la orice alt mesaj.

Media în șabloane. WhatsApp descarcă media din antet de la URL-ul pe care îl indicați, deci URL-ul trebuie să fie valid și accesibil public. Linkurile care cer autentificare nu funcționează. Dacă ați încărcat fișierul cu upload/get-token.js, folosiți URL-ul fișierului construit din acel răspuns.

3. Încărcare media pentru antet

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

Când antetul unui șablon este o imagine, un videoclip sau un document, fișierul are nevoie de o adresă publică de la care WhatsApp îl poate descărca. Acest endpoint vă oferă permisiunea de scurtă durată de a pune fișierul în spațiul de stocare MonoChat.

Câmp	Obligatoriu	Descriere
fileName	da	Numele fișierului cu extensie, de exemplu product.jpg sau promo.pdf.

Fișierele sunt stocate întotdeauna în folderul chat-assets al spațiului dvs. de lucru; exemplele mai vechi care trimit un câmp key continuă să funcționeze, valoarea nu este necesară.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

Răspunsul vă spune unde să puneți fișierul și vă oferă datele de acces pentru a face acest lucru:

Câmp	Descriere
bucket, region, path	Unde ajunge fișierul.
temporaryCredentials	Date de acces doar pentru încărcare, pentru acea singură cale, valabile 15 minute.
baseUrl	Adresa publică a spațiului de stocare. URL-ul fișierului este baseUrl + / + path.

Încărcați imediat fișierul cu orice client S3, folosind aceste date de acces, apoi transmiteți URL-ul său ca parametru HEADER când trimiteți șablonul. Fișierele foarte mari sau formatele pe care WhatsApp nu le acceptă (acceptă formatele uzuale de imagine, video și PDF) eșuează.

Exemplu: un șablon cu antet de imagine

Să presupunem că aveți un șablon aprobat new_product_announcement cu antet de imagine și două variabile în corp (numele clientului și numele produsului) și doriți să îl trimiteți unui client.

1. Listați șabloanele. Apelați template/list.js cu numărul dvs. WhatsApp și găsiți new_product_announcement. Componentele sale arată o variabilă IMAGE în antet și două variabile TEXT în corp.
2. Încărcați imaginea. Apelați upload/get-token.js cu { "fileName": "urun.jpg" }, încărcați fișierul cu datele de acces returnate și construiți URL-ul său din baseUrl și path.
3. Trimiteți șablonul. Apelați template/send.js cu URL-ul fișierului ca parametru HEADER și ["Ayşe", "XYZ Telefon"] ca parametri BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Dacă șablonul ar fi avut variabile de buton, ați adăuga un element BUTTONS în același mod.
4. Deschideți chatul. url-ul din răspuns deschide conversația; când clientul răspunde, aceasta continuă în inbox-ul dvs. MonoChat.

Erori

Un apel eșuat răspunde cu un cod de eroare și un mesaj care spune ce a mers prost. Înregistrați aceste mesaje în sistemul dvs. și afișați utilizatorilor dvs. un mesaj semnificativ acolo unde este nevoie.

Mesaj	Cauză
phoneNumber field is required	template/list.js a fost apelat fără phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	Lipsește un câmp obligatoriu al template/send.js.
Channel not found	phoneNumber nu este un număr WhatsApp al spațiului dvs. de lucru.
Channel is not verified	Numărul WhatsApp este conectat, dar nu este verificat.
Template message not found	Nu există niciun șablon aprobat cu acel nume și acea limbă pe număr. Verificați ortografia și languageCode.
Template message is not approved	Șablonul există, dar nu este aprobat de Meta.
Variable missing: …	variables nu corespunde șablonului, de exemplu șablonul are nevoie de două valori în corp și ați trimis una.
Agent user not found	Nu există niciun agent cu e-mailul din agentEmailAddress.
Customer Channel not found	Identitatea WhatsApp a clientului nu a putut fi creată sau găsită.

Coduri de stare HTTP pe care le puteți întâlni:

• 401 Unauthorized: antetul Authorization: Bearer <API_TOKEN> lipsește sau token-ul este greșit ori expirat. Folosiți un token valid din contul dvs.
• 403 Forbidden: token-ul nu are acces la acest spațiu de lucru sau la această aplicație, de exemplu un tenant slug greșit.
• 404 Not Found: adresa endpoint-ului este greșită. Verificați calea completă /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: o problemă neașteptată în MonoChat sau la furnizorul WhatsApp ori un refuz din partea WhatsApp (numărul nu este pe WhatsApp, clientul v-a blocat, limite de calitate sau de rată). Reîncercați mai târziu și contactați suportul MonoChat dacă problema persistă.

Capturi de ecran

Trimiterea unui șablon WhatsApp aprobat dintr-un CRM, ERP sau sistem de comerț electronic cu un singur apel API prin MonoChatLista șabloanelor WhatsApp aprobate cu variabilele lorTrimiterea unui șablon către un număr nou creează automat clientulUn singur șablon trimis în mai multe limbiȘabloane cu antete de imagine, video, document și PDF

Întrebări frecvente

Are WhatsApp Template API o interfață de utilizare?

Nu. Este o aplicație doar API cu trei endpoint-uri: listarea șabloanelor, trimiterea unui șablon și obținerea datelor de încărcare pentru antetele media.

Ce am nevoie înainte să o pot folosi?

Un număr WhatsApp Business conectat la MonoChat și verificat, șabloane aprobate de Meta și un token API de la Profil › Token-uri API.

Ce se întâmplă când clientul răspunde?

Conversația ajunge în inbox-ul dvs. MonoChat ca oricare alta. Fiecare trimitere returnează și un link direct către conversație, iar o puteți atribui unui agent după e-mail.

Pot trimite către un număr care nu este încă client?

Da. Dacă numărul de telefon nu este încă client, clientul este creat cu numele pe care îl trimiteți.

Cât costă mesajele șablon?

Fiecare mesaj este facturat ca orice mesaj șablon trimis din MonoChat. Meta tarifează șabloanele după categorie și țara destinatarului; folosiți calculatorul de costuri pentru mesaje în masă WhatsApp pentru a estima o trimitere.

Articole conexe

• Session Link
• Bulk Template Message API
• Mesaje șablon
• Aplicații MonoStore