API Templat WhatsApp
Templat pesan WhatsApp adalah pesan yang telah ditulis sebelumnya dan disetujui untuk dikirim di luar jendela percakapan 24 jam yang normal — misalnya pesan selamat datang, pengingat janji temu, atau pesan untuk mengaktifkan kembali pelanggan. API ini memungkinkan Anda untuk mencantumkan, membuat, mengedit, mengirimkan, memeriksa, menghapus, dan mengirim templat secara terprogram.
Semua jalur di bawah ini bersifat relatif terhadap URL dasar API:
https://api.youraiconnector.com/v1
Setiap permintaan harus diautentikasi. Lihat Autentikasi untuk empat metode yang diterima. Contoh di halaman ini menggunakan header X-API-Key (dan satu bentuk parameter kueri untuk cURL).
Catatan: Templat berjalan pada saluran WhatsApp Business API, sehingga bagian API ini memerlukan akses API dan paket yang menyertakan saluran WhatsApp. Tanpa keduanya, permintaan akan ditolak dengan 403.
Bekerja dengan sub-akun (agensi)
Status persetujuan
Karena pesan yang dikirim di luar percakapan terbuka harus ditinjau oleh WhatsApp terlebih dahulu, setiap templat memiliki status persetujuan:
| Status | Arti |
|---|---|
draft |
Dibuat atau disimpan tetapi belum dikirim untuk ditinjau. Anda masih dapat mengeditnya. |
received |
Telah dikirim dan diterima dalam antrean peninjauan. |
pending |
Sedang ditinjau. |
approved |
Disetujui untuk dikirim. |
rejected |
Ditolak. Bidang rejection_reason menjelaskan alasannya; perbaiki, lalu kirim kembali. |
Hanya templat draft dan rejected yang dapat diedit atau dikirim (kembali). Setelah templat berstatus approved, templat tersebut akan dikunci — buat yang baru jika Anda memerlukan perubahan.
Persetujuan otomatis: Beberapa saluran tidak memerlukan langkah peninjauan eksternal. Templat yang dibuat atau dikirim untuk kampanye pada saluran tersebut akan langsung disimpan sebagai
approved, tanpa ID konten (sid).
Templat pada akun yang terhubung dengan Meta
Endpoint ini berfungsi dengan cara yang sama terlepas dari koneksi WhatsApp mana yang dijalankan akun Anda, namun apa yang terjadi di baliknya berbeda:
- Pada koneksi WhatsApp terkelola, templat didaftarkan ke penyedia pesan dan
sidadalah ID konten penyedia tersebut (HXXXXXXXX…). - Pada akun yang nomornya berjalan di Akun WhatsApp Business miliknya sendiri (salah satu opsi koneksi Meta), templat dibuat dan ditinjau di Akun WhatsApp Business tersebut dan
sidadalah ID templat milik Meta sendiri — string numerik seperti"3394843740694756".statustetap menggunakan nilai-nilai dalam tabel di atas, danrejection_reasontetap memuat penjelasan dari Meta.
Terdapat dua endpoint tambahan untuk ini: satu untuk menanyakan koneksi mana yang Anda gunakan, dan satu untuk menyelaraskan daftar templat Anda dengan Akun WhatsApp Business Anda. Templat yang sudah ada di Akun WhatsApp Business akan diimpor ke pustaka Anda melalui sinkronisasi, sehingga GET /whatsapp-templates setelahnya akan mencantumkannya seperti templat lainnya.
Periksa koneksi mana yang digunakan templat
GET /whatsapp-templates/provider
| Bidang | Deskripsi |
|---|---|
provider |
twilio saat templat didaftarkan dengan penyedia pesan terkelola, meta saat templat tersebut berada di Akun WhatsApp Business Anda sendiri. |
lane |
Koneksi Meta mana yang sedang digunakan — meta_cloud_api (aplikasi Meta Anda sendiri) atau meta_embedded (terhubung melalui aplikasi Meta kami). null pada koneksi terkelola. |
waba_id |
Akun WhatsApp Business tempat templat dibuat, atau null. |
templates_enabled |
false saat koneksi Meta belum selesai (tidak ada Akun WhatsApp Business atau token akses yang tersimpan). Membuat atau mengirimkan templat akan gagal dengan 400 sampai koneksi selesai. |
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()
Respons
{
"success": true,
"provider": "meta",
"lane": "meta_cloud_api",
"waba_id": "2357661648036355",
"templates_enabled": true
}
Sinkronisasi templat dari Meta
Menyegarkan status persetujuan setiap templat yang ada di Akun WhatsApp Business Anda, dan mengimpor templat apa pun yang ada di sana tetapi belum ada di pustaka Anda. Aman untuk dipanggil sesering yang Anda inginkan. Pada koneksi terkelola, tidak ada yang perlu disinkronkan, sehingga panggilan tersebut tidak melakukan apa pun dan hanya melaporkan berapa banyak templat yang Anda miliki.
POST /whatsapp-templates/meta-sync
| Bidang | Deskripsi |
|---|---|
imported |
Templat yang ditemukan di Akun WhatsApp Business yang ditambahkan ke pustaka Anda melalui panggilan ini. |
updated |
Templat yang sudah ada yang status atau detailnya berubah. |
total |
Templat di pustaka Anda setelah sinkronisasi. |
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()
Respons
{
"success": true,
"provider": "meta",
"imported": 2,
"updated": 5,
"total": 12
}
Berbicara langsung dengan Meta (lanjutan)
Jika Anda memerlukan sesuatu yang tidak disediakan oleh endpoint di atas — header templat, footer, tombol, atau templat yang dibuat sepenuhnya secara manual — /v1/meta-templates akan meneruskan permintaan Anda langsung ke API templat milik Meta, tanpa menyimpan apa pun di pustaka templat Anda. Ini hanya berfungsi pada akun yang nomornya berjalan di Akun WhatsApp Business mereka sendiri; pada koneksi terkelola, setiap panggilan akan mengembalikan 400 yang meminta Anda untuk menghubungkan aplikasi Meta terlebih dahulu.
| Endpoint | Apa fungsinya |
|---|---|
GET /meta-templates |
Mencantumkan templat di Akun WhatsApp Business Anda beserta status terbarunya. Tambahkan ?name= untuk memfilter ke satu nama templat yang tepat. Mengembalikan { "success": true, "templates": [...] }. |
POST /meta-templates |
Membuat templat dan mengirimkannya untuk ditinjau oleh Meta dalam satu langkah. Memerlukan name, language, dan body (atau array components lengkap sebagai pengganti body). Opsional: variables (array string), category (MARKETING, UTILITY, atau AUTHENTICATION), header, footer, buttons. Mengembalikan 201 dengan { "success": true, "template": {...} }. |
DELETE /meta-templates/{name} |
Menghapus templat berdasarkan nama Meta-nya — setiap bahasa dari templat tersebut. Tambahkan ?hsm_id= dengan ID templat Meta untuk menghapus satu bahasa saja. Mengembalikan { "success": true, "name": "..." }. |
Templat yang ditolak oleh Meta akan mengembalikan 400 dengan penjelasan Meta sendiri di error.
Mencantumkan templat
Mengembalikan semua templat di akun Anda, dengan ringkasan ringan dari masing-masing templat.
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()
Respons
{
"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."
}
]
}
Mendapatkan templat
Mengembalikan detail lengkap dari satu templat, termasuk variabel, status, dan stempel waktunya.
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()
Respons
{
"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"
}
}
Templat yang tidak ada di akun Anda akan mengembalikan 404 dengan { "success": false, "error": "Template not found" }.
Membuat templat
Membuat templat untuk pesan pembuka kampanye dan mengirimkannya untuk disetujui dalam satu langkah.
POST /whatsapp-templates
| Bidang | Wajib | Deskripsi |
|---|---|---|
campaign_id |
Ya | Kampanye tempat templat tersebut berada. |
name |
Ya | Nama untuk templat tersebut. |
language |
Ya | Kode bahasa, contohnya en, es, de, pt_BR, zh_CN. |
body |
Ya | Teks pesan, maksimal 1024 karakter. |
variables |
Tidak | Daftar urut nama variabel yang digunakan dalam isi pesan. |
Placeholder variabel dapat ditulis sebagai {{first_name}}, {first_name}, atau [first_name] — semuanya dinormalisasi ke bentuk kurung kurawal ganda.
Hasilnya bergantung pada saluran kampanye:
- Kampanye WhatsApp Business API: konten dikirim untuk ditinjau oleh WhatsApp. Respons membawa
campaign_status(receivedataupending) dantemplate_sid. - Saluran tanpa langkah peninjauan eksternal: templat disimpan dan disetujui secara otomatis (
campaign_status: "approved",template_sid: null). - Tidak ada saluran WhatsApp pada kampanye: tidak ada yang dibuat dan
campaign_statusadalahnot_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()
Respons (dikirim untuk ditinjau)
{
"success": true,
"campaign_status": "pending",
"template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
Membuat templat mandiri
Membuat templat di pustaka templat Anda tanpa mengaitkannya dengan pesan pembuka kampanye. Ini adalah langkah pembuatan dari siklus hidup yang diikuti oleh sisa halaman ini: buat di sini, edit, kirimkan untuk ditinjau, periksa statusnya, dan hapus saat Anda tidak lagi membutuhkannya.
POST /whatsapp-templates/docs
| Bidang | Wajib | Deskripsi |
|---|---|---|
name |
Ya | Nama untuk templat. |
language |
Ya | Kode bahasa, contohnya en, es, de, pt_BR, zh_CN. |
body |
Ya | Teks pesan, hingga 1024 karakter. |
variables |
Tidak | Daftar urut nama variabel yang digunakan dalam badan pesan. |
status |
Tidak | draft (default) menyimpannya tanpa mengirimkan; submitted langsung mengantrekannya untuk peninjauan WhatsApp. |
type |
Tidak | general (default) atau smart_followup. |
category |
Tidak | marketing, utility, authentication, atau authentication-international. |
campaign_id |
Tidak | Menautkan templat ke salah satu kampanye Anda. |
Templat autentikasi (kode sekali pakai). WhatsApp tidak menerima templat autentikasi teks bebas: isi pesan telah ditetapkan sebelumnya oleh WhatsApp dan templat harus menyertakan tombol “salin kode”. Saat Anda membuat templat dengan
category: "authentication", kami mengirimkannya dalam bentuk tetap tersebut untuk Anda.bodyAnda disimpan sebagai pratinjau yang ditampilkan di aplikasi, namun teks yang diterima kontak Anda adalah kata-kata dari WhatsApp sendiri (kode, pengingat keamanan, dan catatan kedaluwarsa 10 menit). Deklarasikan tepat satu variabel, misalnya["code"], dan teruskan kodenya saat Anda mengirim (lihat kolomvariablesdi Kirim templat ke kontak). Kode harus lebih pendek dari 15 karakter.
Create mana yang harus saya gunakan? Gunakan yang ini jika Anda menginginkan templat yang dapat Anda edit dan kirimkan sendiri. Gunakan
POST /whatsapp-templates(di atas) jika Anda ingin mengatur pesan pembuka kampanye — yang itu memerlukancampaign_iddan langsung ditulis ke dalam kampanye.
Templat yang dibuat sebagai submitted akan dikirim untuk peninjauan WhatsApp di latar belakang, jadi periksa endpoint status untuk mengetahui hasilnya alih-alih mengharapkannya dalam respons.
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()
Respons
{
"success": true,
"template_id": "template_abc123",
"status": "draft"
}
name, language, atau body yang hilang, bahasa yang tidak didukung, status selain draft atau submitted, type atau category yang tidak dikenal, atau badan pesan lebih dari 1024 karakter akan mengembalikan 400 dengan error yang menjelaskan alasannya. campaign_id yang bukan merupakan salah satu kampanye Anda akan mengembalikan 404.
Memperbarui templat
Mengedit templat yang belum disetujui. Hanya templat dengan status draft atau rejected yang dapat diedit. Berikan kombinasi apa pun dari name, body, language, dan variables — hanya bidang yang Anda kirim yang akan diubah.
PUT /whatsapp-templates/{templateId}
Pengeditan tidak mengirim ulang templat untuk ditinjau. Gunakan endpoint kirim setelahnya.
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()
Respons
{
"success": true,
"template_id": "template_abc123"
}
Mencoba mengedit templat yang sudah approved (atau tidak dapat diedit), tidak mengirim kolom apa pun, atau mengirim nilai yang tidak valid akan mengembalikan 400 dengan error penjelasan.
Kirim templat untuk disetujui
Mengirim templat draft atau rejected untuk ditinjau. Templat pada saluran yang tidak memerlukan peninjauan eksternal akan langsung disetujui; semua templat lainnya dikirim ke WhatsApp dan status yang dikembalikan (biasanya received atau pending) disimpan pada templat tersebut.
POST /whatsapp-templates/{templateId}/submit
Templat tindak lanjut harus mendeklarasikan dan menggunakan variabel yang diperlukan sebelum dapat dikirim: placeholder nama depan, ditambah placeholder konteks pribadi untuk tindak lanjut cerdas.
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()
Respons
{
"success": true,
"template_id": "template_abc123",
"status": "pending",
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
Periksa status persetujuan
Endpoint ringan untuk melakukan polling status templat saat ini. Status dibaca dari catatan yang tersimpan, yang diperbarui secara berkala di latar belakang, sehingga persetujuan atau penolakan yang sangat baru mungkin memerlukan waktu singkat untuk muncul.
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()
Respons
{
"success": true,
"template_id": "template_abc123",
"name": "welcome_message",
"status": "approved",
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"rejection_reason": null,
"date_updated": "2026-06-02T08:30:00.000Z"
}
Hapus templat
Menghapus catatan templat dari akun Anda.
DELETE /whatsapp-templates/{templateId}
Penting: Pada koneksi terkelola, hanya catatan tersimpan yang dihapus — konten yang telah disetujui oleh WhatsApp mungkin tetap terdaftar pada penyedia pesan. Pada akun yang berjalan di Akun WhatsApp Business miliknya sendiri, templat juga akan dihapus dari akun tersebut. Bagaimanapun, jika kampanye masih menggunakan templat ini, arahkan ulang kampanye tersebut ke templat lain sebelum menghapusnya, jika tidak, pengiriman yang mengandalkannya akan gagal.
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()
Respons
{
"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."
}
Mengirim templat ke kontak
Mengirim templat yang telah disetujui ke kontak, bahkan saat tidak ada percakapan yang terbuka — ini membuka kembali sesi obrolan. Anda dapat menargetkan kontak berdasarkan contactId atau phoneNumber, dan memilih templat berdasarkan whatsappTemplateId atau templateName.
POST /whatsapp-templates/send
| Kolom | Wajib | Deskripsi |
|---|---|---|
contactId |
Salah satu dari keduanya | ID kontak. |
phoneNumber |
Salah satu dari keduanya | Nomor telepon kontak (dengan kode negara, tanpa spasi). Dicari atau dibuat jika diperlukan. |
whatsappTemplateId |
Salah satu dari keduanya | ID templat. |
templateName |
Salah satu dari keduanya | Nama templat, seperti yang ditampilkan di aplikasi. |
firstName |
Tidak | Digunakan untuk mengisi kontak yang baru dibuat. |
lastName |
Tidak | Digunakan untuk mengisi kontak yang baru dibuat. |
email |
Tidak | Digunakan untuk mengisi kontak yang baru dibuat. |
variables |
Tidak | Nilai eksplisit untuk variabel templat, dikunci berdasarkan nama variabel, misalnya { "code": "482913" }. Nilai yang diberikan di sini lebih diutamakan daripada kolom kontak untuk variabel tersebut; variabel yang Anda lewatkan akan tetap diisi dari kontak seperti yang dijelaskan di bawah. Beginilah cara Anda meneruskan kode sekali pakai ke templat autentikasi. |
Isi templat mendukung substitusi variabel tingkat lanjut:
- Variabel dasar:
{{first_name}},{{email}},{{company}} - Nilai default:
{{first_name|there}}menampilkantherejika bidang kosong - Transformasi:
{{company|uppercase}},{{name|lowercase}},{{name|capitalize}} - Gabungan:
{{company|Your Company|uppercase}}
Kredit: Mengirim templat akan memakan kredit. Biaya pastinya bergantung pada negara penerima dan kategori templat.
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()
Respons
{
"success": true,
"data": "WhatsApp template message sent successfully"
}
Permintaan yang tidak menyertakan pengidentifikasi kontak maupun kedua pengidentifikasi templat akan mengembalikan 400. Jika akun Anda tidak memiliki kredensial pesan yang diperlukan untuk mengirim, responsnya adalah 403.
Membuat atau memperbarui templat langsung kampanye
Sepasang endpoint kedua untuk templat pembuka kampanye, yang dicakup berdasarkan jalur (path) alih-alih campaign_id di dalam body. Ini adalah endpoint yang digunakan untuk kampanye yang sudah aktif: tidak seperti Membuat templat di atas, pembaruan di sini juga mengirimkan ulang draf tindak lanjut kampanye untuk ditinjau, sehingga templat pembuka dan tindak lanjutnya tetap sinkron.
POST /whatsapp-templates/campaign/{campaignId} membuat templat pembuka kampanye. PUT /whatsapp-templates/campaign/{campaignId} mengeditnya — kampanye harus sudah memiliki templat, atau ini akan mengembalikan 400.
| Bidang | Wajib | Deskripsi |
|---|---|---|
name |
Ya | Nama untuk templat. |
language |
Ya | Kode bahasa, contohnya en, es, de, pt_BR, zh_CN. |
body |
Ya | Teks pesan, maksimal 1024 karakter. |
variables |
Ya | Daftar berurutan nama variabel yang digunakan dalam body. Berikan array kosong jika templat tidak menggunakannya. |
cURL (membuat)
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()
Respons
{
"success": true,
"campaign_status": "pending",
"template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"message": "WhatsApp template created and campaign updated successfully."
}
Untuk mengedit, ubah metode ke PUT dan gunakan bidang yang sama — ini akan mengirimkan ulang templat pembuka (dan draf tindak lanjut kampanye, pada kampanye WhatsApp API) untuk ditinjau.
Kampanye yang bukan milik akun Anda akan mengembalikan 404; kampanye milik akun lain yang tidak memiliki otorisasi untuk Anda akan mengembalikan 403. Mengedit kampanye yang tidak memiliki templat yang ada akan mengembalikan 400.
Mengirim templat ke kontak yang sudah ada
Alternatif yang lebih sederhana dan dicakup berdasarkan jalur (path) dibandingkan Mengirim templat ke kontak di atas: baik templat maupun kontak harus sudah ada — tidak ada pencarian berdasarkan nama atau pembuatan secara langsung.
POST /whatsapp-templates/{templateId}/send-to-contact
| Bidang | Wajib | Deskripsi |
|---|---|---|
contactId |
Ya | ID kontak. Harus milik akun Anda. |
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()
Respons
{
"success": true,
"data": "WhatsApp template message sent successfully"
}
Kredit: Pengiriman akan memakan kredit, dengan harga yang sama seperti endpoint di atas.
contactIdyang hilang atau tidak ada di akun Anda akan mengembalikan403;templateIdyang tidak ada akan mengembalikan404.
Mengirim templat secara massal
Kirim satu templat ke banyak kontak dalam satu panggilan, dengan pratinjau biaya yang dapat Anda tampilkan sebelum melakukan pengiriman.
Perkirakan biaya terlebih dahulu
Mengembalikan biaya pengiriman, dirinci berdasarkan negara tujuan, tanpa mengirim apa pun atau menggunakan kredit. Harga templat ditentukan per negara tujuan, jadi ini harus dihitung di sisi server terhadap kontak yang sebenarnya, bukan diestimasi di sisi klien.
POST /whatsapp-templates/{templateId}/estimate-bulk-cost
| Bidang | Wajib | Deskripsi |
|---|---|---|
contactIds |
Ya | Kontak untuk diberi harga, hingga 500 per panggilan. Duplikat dihitung satu kali. |
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()
Respons
{
"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 menghitung id yang hilang, bukan milik Anda, atau tidak memiliki nomor telepon — estimasi hanya mencakup sisanya, jadi nilai bukan nol berarti pengiriman sebenarnya akan menjangkau lebih sedikit kontak daripada yang Anda pilih.
Kirim batch
Mengirim templat ke setiap kontak dalam daftar, menyelesaikan variabel pintar per kontak dan memotong kredit per pengiriman.
POST /whatsapp-templates/{templateId}/bulk-send
| Bidang | Wajib | Deskripsi |
|---|---|---|
contactIds |
Ya | Kontak untuk dikirimi, hingga 5000 per panggilan. |
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()
Respons
{
"success": true,
"data": { "sent": 118, "failed": 2, "total": 120 }
}
Kontak yang gagal (tidak ditemukan, tidak ada di akun Anda, atau kesalahan pengiriman) akan dilewati dan dihitung dalam failed alih-alih menghentikan batch. contactIds yang kosong, lebih dari 5000 id pada pengiriman (500 pada estimasi), atau templateId yang hilang akan mengembalikan 400.
Coba ulang pesan yang gagal
Dua endpoint untuk mengirim ulang pesan yang gagal, tanpa membuat catatan pesan baru atau menggunakan kredit lagi.
POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template mencoba ulang pesan templat yang gagal secara khusus — ini menyelesaikan kembali konten templat dari kampanye jika pesan yang gagal belum memuatnya. Hanya pesan dengan status failed dan tipe template yang dapat dicoba ulang dengan cara ini.
POST /whatsapp-templates/messages/{contactId}/{messageId}/retry bersifat agnostik saluran dan berfungsi untuk pesan non-templat apa pun yang gagal (misalnya WhatsApp Web), mengirimkannya ke jalur pengiriman yang tepat berdasarkan saluran pesan tersebut. Ini menerima status failed, failed_connection, limit_exceeded, atau queued_retry.
Tidak ada endpoint yang memerlukan badan permintaan.
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()
Respons
{
"success": true,
"data": "Message retry initiated successfully"
}
Untuk versi agnostik saluran, ubah jalur ke .../msg_abc789/retry. Pesan yang statusnya tidak memenuhi syarat untuk dicoba ulang, atau (pada endpoint templat) yang bukan merupakan pesan templat, akan mengembalikan 400. Kontak atau pesan yang hilang akan mengembalikan 404.
Profil WhatsApp Business
Kelola profil WhatsApp Business (tentang, alamat, deskripsi, email, situs web, kategori bisnis, dan logo) yang ditampilkan kepada kontak di WhatsApp. Berfungsi baik pada koneksi yang dikelola maupun akun yang menjalankan Akun WhatsApp Business-nya sendiri.
Simpan profil
PUT /whatsapp-templates/profile
| Bidang | Wajib | Deskripsi |
|---|---|---|
phoneNumber |
Ya | Nomor WhatsApp milik profil ini. Harus terhubung di akun Anda. |
about |
Tidak | Teks “Tentang” singkat yang ditampilkan di profil. |
address |
Tidak | Alamat bisnis. |
description |
Tidak | Deskripsi bisnis yang lebih panjang. |
email |
Tidak | Email kontak yang ditampilkan di profil. |
websites |
Tidak | Larik URL situs web. Masing-masing harus berupa URL yang valid. |
vertical |
Tidak | Kategori bisnis, contohnya Retail atau Professional Services. |
profilePictureHandle |
Tidak | Handle yang dikembalikan oleh endpoint unggah-gambar di bawah, untuk mengatur foto 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()
Respons
{
"success": true,
"data": "WhatsApp Business profile updated successfully"
}
phoneNumber yang hilang, URL situs web yang tidak valid, atau phoneNumber yang tidak terhubung di akun Anda akan mengembalikan 400 atau 404.
Unggah foto profil
Mengunduh gambar dari URL yang Anda berikan dan mengunggahnya ke WhatsApp, lalu mengembalikan sebuah handle. Teruskan handle tersebut sebagai profilePictureHandle pada panggilan simpan-profil di atas untuk mengaturnya sebagai foto — endpoint ini hanya mengunggah gambar, tidak mengaturnya secara langsung.
POST /whatsapp-templates/profile/picture
| Bidang | Wajib | Deskripsi |
|---|---|---|
phoneNumber |
Ya | Nomor WhatsApp milik profil ini. |
fileUrl |
Ya | URL yang dapat diakses publik menuju gambar yang akan diunggah. |
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()
Respons
{
"success": true,
"data": "1234567890123456"
}
data adalah handle gambar yang diunggah. phoneNumber atau fileUrl yang hilang, atau phoneNumber tanpa token akses WhatsApp dalam file, akan mengembalikan 400; fileUrl yang tidak dapat dijangkau atau tidak valid akan mengembalikan kesalahan yang menjelaskan alasan kegagalan pengunduhan.
Periksa status pengirim
Melakukan polling (dan menyegarkan) status pengiriman langsung nomor WhatsApp yang terhubung dengan penyedia pesan. Berguna untuk memastikan nomor tersebut benar-benar dapat mengirim pesan sebelum Anda mengandalkannya.
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()
Respons
{
"success": true,
"data": "ONLINE"
}
data adalah salah satu dari ONLINE (mengirim secara normal), PENDING (masih diverifikasi), atau DELETED (penyedia tidak lagi mengenali pengirim ini — hubungkan kembali nomor tersebut). phoneNumber tanpa informasi bisnis WhatsApp dalam file akan mengembalikan 404.
Hasilkan templat tindak lanjut dengan AI
Platform ini dapat menulis templat tindak lanjut WhatsApp untuk kampanye Anda — pengingat yang dikirim saat percakapan menjadi senyap — berdasarkan instruksi dan tujuan kampanye itu sendiri. Terdapat satu endpoint pekerjaan yang berjalan di latar belakang, ditambah tiga endpoint lama yang dipertahankan untuk integrasi yang sudah ada. Semuanya menggunakan kredit AI.
Memulai pekerjaan pembuatan
POST /campaigns/{campaignId}/template-generation
| Bidang | Wajib | Deskripsi |
|---|---|---|
type |
Tidak | all (default) menulis seluruh rangkaian tindak lanjut. cold_only hanya menulis pesan untuk kontak yang tidak pernah membalas. |
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()
Respons (202)
{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }
Panggilan akan kembali segera setelah pekerjaan dimasukkan ke dalam antrean. Baca kampanye (GET /campaigns/{campaignId}, lihat API Kampanye) dan pantau objek template_generation_status-nya hingga selesai:
| Bidang | Deskripsi |
|---|---|
status |
processing saat pekerjaan berjalan, lalu completed atau failed. |
progress |
0 hingga 100. |
current_template, total_templates |
Berapa banyak templat yang telah ditulis sejauh ini, dari total yang akan ditulis oleh pekerjaan tersebut — 11 untuk kampanye keluar atau gabungan, 9 jika tidak. |
error |
Alasan pekerjaan failed berhenti, misalnya karena kredit tidak mencukupi. |
started_at, completed_at |
Kapan pekerjaan dimulai dan berakhir. |
Templat yang dihasilkan akan muncul di kampanye seperti templat lainnya, sehingga akan terlihat di Daftar templat dan tetap melalui persetujuan WhatsApp sebelum dapat dikirim. 400 berarti type adalah sesuatu selain all atau cold_only; 404 berarti kampanye tersebut tidak ada atau milik akun lain. |
Agen memiliki kembaran dari panggilan ini, POST /agents/{agentId}/template-generation, yang menulis tindak lanjut untuk Agen dan selesai selama panggilan dalam kasus biasa — lihat Hasilkan pesan tindak lanjut di API Agen AI.
Endpoint pembuatan lama
Tiga endpoint sebelumnya melakukan pekerjaan yang sama dan dipertahankan agar integrasi yang ada tetap berjalan. Kode baru sebaiknya menggunakan endpoint pekerjaan di atas.
| Endpoint | Apa fungsinya |
|---|---|
POST /whatsapp-templates/campaign/{campaignId}/generate-async |
Memulai pembuatan tindak lanjut untuk kampanye di latar belakang dan mengembalikan 202 dengan { "success": true, "data": { "result": "success", "message": "..." } }. Kredit dibebankan di muka (dilewati pada akun yang membawa kunci AI sendiri) dan template_generation_status kampanye melaporkan kemajuan persis seperti di atas. |
POST /whatsapp-templates/campaign/{campaignId}/generate-followups |
Menghasilkan kesembilan templat tindak lanjut selama panggilan — untuk kampanye yang dibuat sebelum tindak lanjut otomatis ada, atau kampanye yang perlu ditulis ulang — dan mengembalikan 200 dengan templatesGenerated di dalam data. |
POST /whatsapp-templates/agent/{agentId}/generate-followups |
Pembuatan sinkron yang sama yang ditangani oleh Agen. Respons menambahkan agent_id, campaign_id dan target: "campaign" saat templat ditulis ke kampanye Agen, "agent" (dengan campaign_id: null) saat Agen tidak memiliki kampanye dan templat disimpan pada Agen itu sendiri. Agen yang hilang atau asing adalah 404. |
Ketiganya memerlukan tindak lanjut otomatis pada akun dan kredit yang cukup — 400 menyebutkan mana yang kurang — dan pasangan yang ditujukan untuk kampanye mengembalikan 403 saat kampanye milik akun lain.
Kesalahan API Templat
Endpoint templat mengembalikan amplop kesalahan standar:
{
"success": false,
"error": "Template not found"
}
404 pada endpoint ini biasanya berarti sumber daya tidak ditemukan — entah karena tidak ada atau milik akun lain. Beberapa endpoint (pembuatan/pembaruan dengan cakupan kampanye, dan pengiriman ke kontak yang sudah ada) mengembalikan 403 sebagai gantinya jika kampanye atau kontak tersebut milik orang lain, bukan karena tidak ada sama sekali. Beberapa endpoint juga menyertakan kolom error_code yang mencerminkan status HTTP. Kode bersama yang dapat dikembalikan oleh setiap endpoint — 400, 401, 403 (paket Anda tidak menyertakan akses API), 429 (batas kecepatan), dan 500 — tercantum beserta panduan percobaan ulang di Errors & Pagination.
Langkah berikutnya
- Autentikasi — empat cara untuk mengautentikasi permintaan.
- Error & Batas Kecepatan — kode status dan batas 300 permintaan/menit.
- API Kampanye — mengelola kampanye tempat templat dilampirkan.