WhatsApp Template API

API Developer

Kirim template WhatsApp yang disetujui dari sistem Anda sendiri dengan satu panggilan API; percakapan lalu berlanjut di MonoChat.

• WhatsApp
• REST API
• Khusus API

Pasang dari MonoStoreLihat di monochat.ai

Ringkasan

WhatsApp Template API memungkinkan CRM, ERP, situs e-commerce, atau backend apa pun mengirim pesan template WhatsApp yang disetujui kepada pelanggan melalui MonoChat. Satu permintaan menyebutkan nomor WhatsApp pengirim, nomor telepon pelanggan, template, dan variabelnya.

Saat pelanggan membalas, percakapan masuk ke kotak masuk MonoChat Anda seperti percakapan lainnya. Aplikasi ini tidak punya layar sendiri: semuanya berjalan melalui tiga endpoint API.

Sorotan

• Satu panggilan API. Kirim template menurut nama dan bahasa, dengan variabel header, body, tombol, dan carousel yang diisi dari data Anda.
• Langsung ke chat. Setiap pengiriman mengembalikan id percakapan dan tautan langsung ke percakapan itu di MonoChat.
• Pelanggan baru diterima. Jika nomor telepon belum menjadi pelanggan, pelanggan dibuat dengan nama yang Anda kirim.

Pasang dan siapkan

1. Hubungkan nomor WhatsApp Business Anda ke MonoChat dan pastikan nomor itu terverifikasi dan memiliki template yang disetujui Meta.
2. Pasang WhatsApp Template API dari Pengaturan › MonoStore › Aplikasi, atau buka tautan instalasi app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Jika Anda belum punya akun MonoChat, tautan ini memungkinkan Anda mendaftar terlebih dahulu dan memasang aplikasinya untuk Anda.
3. Buat token API di Profil › Token API. Token hanya ditampilkan sekali, jadi salin segera.
4. Panggil template/list.js untuk melihat template Anda yang disetujui beserta variabelnya.
5. Panggil template/send.js dengan nomor pelanggan dan nilai variabel untuk mengirim template pertama Anda.

catatan

• Setiap pesan ditagih seperti pesan template lain yang dikirim dari MonoChat.
• URL media harus tetap dapat diakses sampai WhatsApp selesai mengambil file.
• Kirim ke pelanggan yang setuju menerima pesan dari Anda: WhatsApp dapat membatasi nomor yang pesannya diblokir atau dilaporkan.

Fitur

Tampilkan daftar template

Template yang disetujui dari sebuah nomor WhatsApp, lengkap dengan bahasa, kategori, status, dan variabelnya, sehingga sistem Anda tahu apa yang dapat dikirim.

Kirim template

Menurut nama dan bahasa template, dengan variabel header, body, tombol, dan carousel. Nilai yang hilang menghentikan pengiriman, sehingga tidak ada yang terisi setengah sampai ke pelanggan.

Tugaskan ke agen

Berikan email agen dan percakapan dibuka atas namanya.

Header media

Dapatkan kredensial unggah berumur singkat, taruh gambar, video, atau dokumen di penyimpanan MonoChat, dan gunakan URL-nya sebagai header template.

Tautan percakapan

Setiap pengiriman mengembalikan id sesi, id pesan, dan tautan yang membuka percakapan di MonoChat.

Kesalahan yang jelas

Panggilan yang gagal menyebutkan apa yang salah, misalnya “Channel not found” atau “Variable missing”.

Sebelum Anda mulai

• Nomor WhatsApp Business Anda terhubung ke MonoChat dan terverifikasi. Lihat Saluran.
• Template yang ingin Anda kirim sudah disetujui Meta. Template adalah cara Anda menulis lebih dulu, atau menghubungi pelanggan di luar jendela 24 jam. Lihat Pesan Templat.
• Anda memiliki token API dari Profil › Token API. Lihat Token API.
• Anda tahu tenant slug Anda: bagian setelah /tenants/ di alamat MonoChat Anda. Pada https://app.monochat.ai/tenants/mybusiness slug-nya adalah mybusiness.

Referensi API

Aplikasi ini tidak punya layar sendiri. Semuanya berjalan melalui tiga endpoint, masing-masing berupa POST dengan isi JSON:

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

Endpoint	Fungsinya
template/list.js	Menampilkan template dari salah satu nomor WhatsApp Anda, beserta variabelnya.
template/send.js	Mengirim template ke pelanggan dan mengembalikan tautan ke percakapan.
upload/get-token.js	Memberikan kredensial unggah berumur singkat untuk gambar, video, atau dokumen header.

Nomor telepon selalu ditulis dengan kode negara dan tanpa +, misalnya 905334445566. Panggilan yang berhasil menjawab 200 dengan data endpoint di bawah result.

1. Tampilkan template

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

Menampilkan setiap template dari nomor WhatsApp Business yang diberikan: nama, kode bahasa, kategori, komponen (header, body, footer, tombol), jenis variabel, dan status persetujuan.

Kolom	Wajib	Deskripsi
phoneNumber	ya	Nomor WhatsApp Business Anda di MonoChat, dengan kode negara, tanpa +.
options	tidak	Penomoran halaman dan filter, misalnya { "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"
}

Respons (diringkas):

{
  "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 }
    }
  }
}

Cara membacanya:

• name: nama sistem yang Anda gunakan untuk mengirim template.
• languageCode: bahasa pengiriman template.
• category: kategori WhatsApp (MARKETING, UTILITY, AUTHENTICATION).
• components: bagian-bagian penyusun template.

Komponen	Isi	Deskripsi
HEADER	IMAGE, VIDEO, DOCUMENT atau teks	Untuk media, format diberikan; variabel muncul di bawah variables.
BODY	Teks dengan variabel	Isi pesan, dengan placeholder seperti {{1}}, {{2}}.
FOOTER	Teks	Biasanya tanpa variabel.
BUTTONS	URL, balasan cepat…	Teks tombol dan variabelnya, jika ada.

Template contoh di atas membutuhkan satu gambar untuk header dan dua teks untuk body (nama pelanggan dan nama produk). Footer-nya tetap ("Teşekkürler") dan tidak ada tombol.

2. Kirim template

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

Mengirim template yang disetujui ke pelanggan. Jika nomor telepon belum menjadi pelanggan, pelanggan dibuat; percakapan dibuka (atau dipakai ulang) dan template dikirim di dalamnya.

Kolom	Wajib	Deskripsi
phoneNumber	ya	Nomor WhatsApp Business pengirim. Harus terhubung ke MonoChat dan terverifikasi.
templateMessageName	ya	name template, persis seperti yang dikembalikan daftar.
languageCode	ya	Bahasa template, seperti yang dikembalikan daftar (misalnya tr-TR).
customerPhoneNumber	ya	Nomor WhatsApp pelanggan.
variables	jika template memilikinya	Nilai variabel template (lihat di bawah).
customerFirstName, customerLastName	tidak	Dipakai saat pelanggan baru di MonoChat.
agentEmailAddress	tidak	Menugaskan percakapan ke agen dengan email ini.

Variabel. Setiap item array variables memiliki type dan daftar parameters, diberikan sesuai urutan placeholder template:

type	parameters
HEADER	Variabel teks header, atau URL publik gambar, video, atau dokumen header.
BODY	{{1}}, {{2}}, … pada body secara berurutan.
BUTTONS	Satu nilai untuk setiap tombol yang memiliki variabel (misalnya bagian dinamis tombol URL atau kode kupon), sesuai urutan tombol.
CAROUSEL	Sebagai ganti parameters, array cards dengan satu entri per kartu carousel, masing-masing dengan components sendiri.

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

Nilai yang hilang menghentikan pengiriman dengan Variable missing, sehingga tidak ada yang terisi setengah sampai ke pelanggan. FOOTER jarang memiliki variabel.

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"] }
  ]
}

Respons:

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

• url: membuka percakapan di MonoChat, bagi orang yang sudah masuk dan berhak melihatnya.
• sessionId: id percakapan.
• messageId: id pesan di MonoChat. Status terkirim dan terbacanya muncul di chat seperti pesan lainnya.

Media di template. WhatsApp mengunduh media header dari URL yang Anda berikan, jadi URL harus valid dan dapat diakses publik. Tautan yang memerlukan login tidak berfungsi. Jika Anda mengunggah file dengan upload/get-token.js, gunakan URL file yang dibangun dari jawaban tersebut.

3. Unggah media untuk header

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

Saat header template berupa gambar, video, atau dokumen, file membutuhkan alamat publik tempat WhatsApp dapat mengunduhnya. Endpoint ini memberi Anda izin berumur singkat untuk menaruh file di penyimpanan MonoChat.

Kolom	Wajib	Deskripsi
fileName	ya	Nama file beserta ekstensinya, misalnya product.jpg atau promo.pdf.

File selalu disimpan di folder chat-assets workspace Anda; contoh lama yang mengirim kolom key tetap berfungsi, nilainya tidak diperlukan.

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

{
  "fileName": "product.jpg"
}

Jawabannya memberi tahu di mana menaruh file dan memberikan kredensial untuk melakukannya:

Kolom	Deskripsi
bucket, region, path	Tempat file disimpan.
temporaryCredentials	Kredensial khusus unggah untuk satu path itu, berlaku 15 menit.
baseUrl	Alamat publik penyimpanan. URL file adalah baseUrl + / + path.

Unggah file segera dengan klien S3 mana pun menggunakan kredensial ini, lalu berikan URL-nya sebagai parameter HEADER saat Anda mengirim template. File yang sangat besar atau format yang tidak didukung WhatsApp (WhatsApp menerima format gambar, video, dan PDF yang umum) akan gagal.

Contoh: template dengan header gambar

Misalkan Anda punya template yang disetujui new_product_announcement dengan header gambar dan dua variabel body (nama pelanggan dan nama produk), dan Anda ingin mengirimkannya ke pelanggan.

1. Tampilkan daftar template. Panggil template/list.js dengan nomor WhatsApp Anda dan temukan new_product_announcement. Komponennya menunjukkan satu variabel IMAGE di header dan dua variabel TEXT di body.
2. Unggah gambar. Panggil upload/get-token.js dengan { "fileName": "urun.jpg" }, unggah file dengan kredensial yang dikembalikan, dan bangun URL-nya dari baseUrl dan path.
3. Kirim template. Panggil template/send.js dengan URL file sebagai parameter HEADER dan ["Ayşe", "XYZ Telefon"] sebagai parameter BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Jika template memiliki variabel tombol, Anda menambahkan item BUTTONS dengan cara yang sama.
4. Buka chat. url dari jawaban membuka percakapan; saat pelanggan membalas, percakapan berlanjut di kotak masuk MonoChat Anda.

Error

Panggilan yang gagal menjawab dengan status error dan pesan yang menjelaskan apa yang salah. Catat pesan-pesan ini di sistem Anda dan tampilkan pesan yang bermakna kepada pengguna Anda bila perlu.

Pesan	Penyebab
phoneNumber field is required	template/list.js dipanggil tanpa phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	Kolom wajib pada template/send.js tidak ada.
Channel not found	phoneNumber bukan nomor WhatsApp di workspace Anda.
Channel is not verified	Nomor WhatsApp terhubung tetapi belum terverifikasi.
Template message not found	Tidak ada template yang disetujui dengan nama dan bahasa itu pada nomor tersebut. Periksa ejaan dan languageCode.
Template message is not approved	Template ada tetapi belum disetujui Meta.
Variable missing: …	variables tidak sesuai dengan template, misalnya template membutuhkan dua nilai body dan Anda mengirim satu.
Agent user not found	Tidak ada agen dengan email di agentEmailAddress.
Customer Channel not found	Identitas WhatsApp pelanggan tidak dapat dibuat atau ditemukan.

Kode status HTTP yang mungkin Anda temui:

• 401 Unauthorized: header Authorization: Bearer <API_TOKEN> tidak ada, atau token salah atau kedaluwarsa. Gunakan token yang valid dari akun Anda.
• 403 Forbidden: token tidak memiliki akses ke workspace atau aplikasi ini, misalnya tenant slug yang salah.
• 404 Not Found: alamat endpoint salah. Periksa path lengkap /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: masalah tak terduga di MonoChat atau di penyedia WhatsApp, atau penolakan dari sisi WhatsApp (nomor tidak ada di WhatsApp, pelanggan memblokir Anda, batas kualitas atau laju). Coba lagi nanti dan hubungi dukungan MonoChat jika berlanjut.

Tangkapan layar

Mengirim template WhatsApp yang disetujui dari CRM, ERP, atau sistem e-commerce dengan satu panggilan API melalui MonoChatDaftar template WhatsApp yang disetujui beserta variabelnyaMengirim template ke nomor baru membuat pelanggan secara otomatisSatu template dikirim dalam beberapa bahasaTemplate dengan header gambar, video, dokumen, dan PDF

FAQ

Apakah WhatsApp Template API memiliki antarmuka pengguna?

Tidak. Ini aplikasi khusus API dengan tiga endpoint: daftar template, kirim template, dan dapatkan kredensial unggah untuk header media.

Apa yang saya perlukan sebelum dapat menggunakannya?

Nomor WhatsApp Business yang terhubung ke MonoChat dan terverifikasi, template yang disetujui Meta, dan token API dari Profil › Token API.

Apa yang terjadi saat pelanggan membalas?

Percakapan masuk ke kotak masuk MonoChat Anda seperti percakapan lainnya. Setiap pengiriman juga mengembalikan tautan langsung ke percakapan, dan Anda dapat menugaskannya ke agen lewat email.

Bisakah saya mengirim ke nomor yang belum menjadi pelanggan?

Bisa. Jika nomor telepon belum menjadi pelanggan, pelanggan dibuat dengan nama yang Anda kirim.

Berapa biaya pesan template?

Setiap pesan ditagih seperti pesan template lain yang dikirim dari MonoChat. Meta menetapkan harga template menurut kategori dan negara penerima; gunakan kalkulator biaya pesan massal WhatsApp untuk memperkirakan sebuah pengiriman.

Terkait

• Session Link
• Bulk Template Message API
• Pesan Templat
• Aplikasi MonoStore