Kirim Pesan WhatsApp via API: Contoh cURL, Node, Python, PHP

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F campaignName=order-updates \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=order_update \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=INV-400

// Node.js 18+ (fetch dan FormData bawaan)
const form = new FormData();
form.append("batchId", "0");
form.append("campaignName", "order-updates");
form.append("destinationNo", "971500000000");
form.append("messageType", "TEMPLATE");
form.append("templateName", "order_update");
form.append("templateLanguage", "en_US");
form.append("bodyTemplateVariables", "INV-400");

const res = await fetch("https://api.broadnet.me/whatsapp/message/sendbulk", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BROADNET_TOKEN}` }, // fetch mengatur boundary multipart
  body: form,
});
console.log(await res.json());

import os
import requests

fields = {
    "batchId": "0",
    "campaignName": "order-updates",
    "destinationNo": "971500000000",
    "messageType": "TEMPLATE",
    "templateName": "order_update",
    "templateLanguage": "en_US",
    "bodyTemplateVariables": "INV-400",
}
# Kirim setiap field sebagai bagian multipart (files=), bukan url-encoded (data=).
r = requests.post(
    "https://api.broadnet.me/whatsapp/message/sendbulk",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    files={k: (None, v) for k, v in fields.items()},
    timeout=30,
)
print(r.json())

<?php
$ch = curl_init("https://api.broadnet.me/whatsapp/message/sendbulk");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BROADNET_TOKEN")],
    // Array (bukan string) membuat cURL mengirim multipart/form-data.
    CURLOPT_POSTFIELDS => [
        "batchId" => "0",
        "campaignName" => "order-updates",
        "destinationNo" => "971500000000",
        "messageType" => "TEMPLATE",
        "templateName" => "order_update",
        "templateLanguage" => "en_US",
        "bodyTemplateVariables" => "INV-400",
    ],
]);
echo curl_exec($ch);
curl_close($ch);

{
  "totalFiles": 1,
  "totalSuccess": 1,
  "totalFailed": 0,
  "totalDuplicates": 0,
  "batchId": "2609091405000000001",
  "fileResults": [
    {
      "fileName": "direct",
      "totalRecords": 1,
      "successCount": 1,
      "failedRecipients": [],
      "duplicateRecipients": []
    }
  ],
  "message": "Messages queued for delivery"
}

Field request mana yang paling penting?

Field mana yang wajib bergantung pada messageType. Berikut yang umum.

Penjadwalan memakai scheduled, scheduleTime, dan gmt, dan delay mengatur laju pengiriman. Daftar lengkapnya ada di referensi WhatsApp API.

Bagaimana mengirim template dengan tombol atau OTP?

Tambahkan nilai tombol di buttonsTemplateVariable. Untuk template autentikasi dengan tombol salin kode, berikan kode itu di field body maupun field tombol.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=login_code \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=482913 \
  -F buttonsTemplateVariable=482913

Di sini login_code adalah placeholder untuk template autentikasi Anda sendiri yang sudah disetujui. Untuk beberapa tombol, buttonsTemplateVariable menerima array JSON. Buat kode di server Anda, simpan dalam bentuk hash dengan masa berlaku, dan jangan pernah mencatatnya di log. Panduan OTP kami membahas pengiriman one-tap, zero-tap, dan salin kode.

Bagaimana membalas di dalam jendela layanan pelanggan?

Gunakan tipe pesan sesi. Balasan teks biasa membutuhkan messageType=TEXT dan content.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEXT \
  -F campaignName=support \
  -F "content=Your order has shipped. Reply here if you need anything."

Untuk tombol balasan, kirim messageType=INTERACTIVE dan interactivePayload yang mengikuti format pesan interaktif Meta.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=INTERACTIVE \
  -F campaignName=support \
  -F 'interactivePayload={"type":"button","body":{"text":"Confirm your delivery slot?"},"action":{"buttons":[{"type":"reply","reply":{"id":"slot_ok","title":"Confirm"}},{"type":"reply","reply":{"id":"slot_change","title":"Change"}}]}}'

Untuk menandai pesan masuk sebagai sudah dibaca, dan secara opsional menampilkan indikator mengetik, panggil POST /whatsapp/message/read dengan JSON:

curl -X POST https://api.broadnet.me/whatsapp/message/read \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "messageId": "wamid.HBgMOTcxNTAwMDAwMDAwFQIAEhgg", "typing": true }'

Lihat panduan kami tentang pesan interaktif untuk arahan desain.

Bagaimana melacak pengiriman?

Status dikirim (push) ke webhook yang dikonfigurasi di akun Anda dan juga dapat dibaca per batch. Setiap penerima bergerak melalui SUBMITTED, SENT, DELIVERED, dan READ, atau berakhir sebagai FAILED atau REJECTED beserta alasannya.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&status=FAILED&page=0&size=50" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id wajib; status, destination, search, page, dan size opsional, dan page dimulai dari nol. Gunakan polling sebagai cadangan untuk event yang terlewat, dan bangun penerima Anda seperti dijelaskan di panduan webhook kami. Batch juga dapat dijeda, dilanjutkan, dan dibatalkan dengan endpoint batch dalam referensi.

Error apa yang harus ditangani?

Baca status HTTP terlebih dahulu, lalu body error. API memunculkan error dalam body JSON lima field, dan kegagalan khusus WhatsApp dapat berasal dari Meta.

Panduan kode error kami menjelaskan kode Meta yang umum. Karena tidak ada idempotency key, ikuti langkah perlindungan duplikasi di Error dan batas: tulis catatan pending terlebih dahulu, simpan batchId yang dikembalikan, dan setelah timeout periksa status sebelum mengirim lagi.

Contoh kasus: layanan notifikasi pesanan

"Souq Rafiq" (fiktif), pengecer di UEA, mengirim template order_update saat pesanan dikirim.

1. Layanan pesanan menulis baris dengan kunci order-8842-shipped berstatus pending.
2. Layanan memanggil sendbulk dengan template dan nomor pesanan sebagai bodyTemplateVariables.
3. Pada 200, layanan menyimpan batchId dan menandai baris accepted.
4. Handler webhook memperbarui baris menjadi DELIVERED atau READ, atau FAILED beserta alasannya.
5. Jika pelanggan membalas, alat dukungan memakai pesan sesi TEXT di dalam jendela.
6. Job malam hari membaca bulk-insights untuk batch kemarin dan merekonsiliasi status yang hilang.

Apa saja kesalahan umum?

• Mengirim JSON. Endpoint pengiriman WhatsApp memakai multipart; Content-Type: application/json tidak akan berfungsi.
• data= di Python alih-alih files=, yang meng-encode form sebagai url-encoded.
• Teks bebas di luar jendela, yang gagal. Gunakan template.
• Kode bahasa yang salah, seperti en alih-alih en_US milik template.
• Menganggap 200 sebagai terkirim. Artinya diantrekan.
• Pengulangan buta setelah timeout, yang dapat mengirim pesan dua kali kepada pelanggan.
• Token di kode sisi klien. Panggil API hanya dari backend Anda.
• Batasan: detail payload bervariasi menurut template. Konfirmasikan tata letak variabel untuk kampanye personal pertama Anda bersama tim kami.

Bagaimana OmniChannels.ai membantu

BroadNet adalah Meta Business Solution Provider resmi, dan onboarding ke WhatsApp Business API memakai Meta Embedded Signup; tim kami menyiapkan registrasi bersama Anda, sementara persetujuan tetap di tangan Meta. REST API didokumentasikan dengan spesifikasi OpenAPI 3.1 dan SDK TypeScript, @broadnet/cpaas-sdk, dan status pengiriman dinormalisasi di semua kanal. Mulailah dengan dokumentasi WhatsApp API atau quickstart.