API: Hantar Mesej & Templat WABA

Endpoint penghantaran menghasilkan mesej sebenar. Uji menggunakan nombor milik anda atau penerima yang bersetuju, dengan instance yang telah disahkan.

Urutan penggunaan

1. Dapatkan instanceId melalui GET /api/v1/instances dan semak sambungannya.
2. Tentukan penerima dalam format antarabangsa. Contoh 60123456789 ialah placeholder tutorial; gantikan dengan nombor ujian anda.
3. Untuk WABA, semak sesi perbualan melalui endpoint session-window sebelum memilih mesej biasa atau templat.
4. Sediakan header X-API-Key dan Content-Type: application/json.
5. Hantar satu permintaan, baca respons dan semak Live Chats sebelum mengulang.

Hantar teks

POST /api/v1/send

{
  "to": "60123456789",
  "type": "text",
  "message": "Ini mesej ujian daripada integrasi.",
  "instanceId": 1
}

to ialah penerima, type jenis mesej, message kandungan teks dan instanceId ID sambungan. Gantikan ID 1 dengan ID sebenar.

Hantar gambar

{
  "to": "60123456789",
  "type": "image",
  "mediaUrl": "https://example.com/image.jpg",
  "caption": "Maklumat produk",
  "instanceId": 1
}

mediaUrl mesti merujuk fail yang boleh dicapai oleh perkhidmatan penghantaran; URL contoh di atas bukan fail operasi anda.

Hantar dokumen

{
  "to": "60123456789",
  "type": "document",
  "mediaUrl": "https://example.com/file.pdf",
  "fileName": "panduan.pdf",
  "instanceId": 1
}

Semak format dan saiz fail yang disokong. Endpoint turut menyokong jenis media lain mengikut spesifikasi semasa; jangan anggap semua medan gambar terpakai untuk setiap jenis.

Hantar templat WABA

POST /api/v1/send-template

{
  "to": "60123456789",
  "templateName": "hello_world",
  "language": "en",
  "components": [],
  "instanceId": 1
}

Gunakan nama serta bahasa templat yang benar-benar diluluskan pada akaun berkenaan. components kosong hanya sesuai apabila templat tidak memerlukan parameter. Lengkapkan komponen mengikut struktur templat sebenar.

Semak hasil dan atasi masalah

Simpan messageId atau rujukan yang dipulangkan. Respons diterima/queued tidak semestinya delivery atau read. Jika gagal, semak instance, nombor, media, pemboleh ubah dan status templat. Jika timeout, semak chat/laporan sebelum retry untuk mengelakkan mesej pendua.

Medan API penghantaran satu per satu

Rujuk Settings > Developers > Messaging atau WABA untuk contoh rasmi semasa. POST /api/v1/send mengesan jenis instance dan menghantar melalui laluan yang sesuai.

Rujukan setiap butang dan medan

Butang / medan	Fungsi dan cara penggunaan
instanceName	Nama instance yang tepat; semak melalui Management, bukan meneka daripada nama profil.
number	Nombor penerima individu dalam format yang diminta spesifikasi. Gunakan nombor ujian sendiri untuk ujian yang dibenarkan.
groupJid	Sasaran kumpulan bagi Baileys/Web, menggantikan number; ambil daripada GET /api/v1/groups. WABA tidak menyokong penghantaran kumpulan melalui laluan ini.
type: text / message	Teks mesej untuk dihantar.
type: image / mediaUrl / message	URL imej dan caption pilihan.
type: document / mediaUrl / fileName / mimetype	Pautan dokumen, nama fail dan jenis MIME yang betul.
type: audio / mediaUrl	URL fail audio yang boleh dicapai.
type: template / templateName / templateLanguage	Nama serta bahasa templat ketika menggunakan /send.
variables	Peta nilai dinamik yang sepadan dengan templat diluluskan.

Endpoint khusus templat WABA

POST /api/v1/send-template menggunakan instanceName, number, templateName, language dan variables. Perhatikan nama medan bahasa: endpoint ini menggunakan language, manakala contoh jenis template dalam /send menggunakan templateLanguage.

Kunci bernombor dalam variables mengisi teks dinamik. button_0 dan button_1 mengisi bahagian dinamik URL butang mengikut indeks; button_url ialah fallback. header_image, header_video, header_document dan header_document_filename digunakan bagi header media. Katalog menggunakan catalog_product_id; Multi Product menggunakan mpm_sections (rentetan JSON), mpm_thumbnail_id atau mpm_product_id mengikut spesifikasi.

Sebelum penghantaran WABA

Gunakan rujukan GET /api/v1/templates?instanceName=... untuk templat approved, dan GET /api/v1/session-window untuk menyemak tetingkap perbualan bagi nombor yang dibenarkan. Halaman WABA menerangkan bahawa teks/media memerlukan tetingkap perbualan aktif; di luar tetingkap, gunakan templat yang sesuai. POST /api/v1/templates/sync menyegerakkan rekod templat daripada Meta dan merupakan perubahan data.

Membaca hasil

Respons success menunjukkan permintaan diterima pada laluan tersebut. Untuk Baileys dengan anti-ban aktif, respons boleh mempunyai queued: true serta queueId; ini bermaksud beratur dan belum semestinya telah dihantar. Semak status penghantaran/ralat selepas itu. Jangan mengulang request menghantar secara membuta tuli kerana boleh menghasilkan mesej pendua.

Sediakan payload dengan placeholder dahulu, semak sasaran dan hanya laksanakan selepas ujian penghantaran diluluskan. Tiada request penghantaran dilaksanakan dalam panduan ini.

Screenshot rujukan menu

Padankan nama butang pada gambar dengan penerangan di atas. Maklumat sensitif tidak ditunjukkan dalam screenshot panduan.