Your AI Connector Docs

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 sid adalah 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 sid adalah ID templat milik Meta sendiri — string numerik seperti "3394843740694756". status tetap menggunakan nilai-nilai dalam tabel di atas, dan rejection_reason tetap 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 (received atau pending) dan template_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_status adalah not_applicable.

cURL

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

JavaScript

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

Python

import requests

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

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. body Anda 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 kolom variables di 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 memerlukan campaign_id dan 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}} menampilkan there jika 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. contactId yang hilang atau tidak ada di akun Anda akan mengembalikan 403; templateId yang tidak ada akan mengembalikan 404.


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