Gambaran
API Integrasi cshub adalah laluan luaran untuk menghantar mesej WhatsApp dari backend atau alat automasi anda. Pengesahan melalui Local API Key per perniagaan (parity dengan whatscrmhub Laravel). Endpoint ini berasingan daripada endpoint dalaman yang digunakan oleh panel cshub dan aplikasi mudah alih.
Base URL
https://api.cshub.id/api/v1
Content-Type
application/json
Pengesahan
Pengesahan menggunakan Local API Key di dalam body permintaan (medan `api_key`), bukan header HTTP. Setiap perniagaan mendapat satu Local API Key (UUID) yang dijana secara automatik semasa perniagaan dicipta.
Tiada JWT, tiada header token
Berbeza dengan endpoint dalaman panel. Cukup letak `api_key` dalam body, pelayan menyelesaikan perniagaan dari situ. Layan Local API Key seperti kata laluan — jangan commit ke repo awam, jangan dedahkan dalam frontend.
Cara mendapatkan Local API Key
- Log masuk ke panel cshub di /app.
- Buka Settings → API Key (atau Profile → Integration).
- Salin Local API Key. Boleh dijana semula bila-bila masa — yang lama segera tidak sah.
Endpoint
Satu endpoint meliputi semua hantar WhatsApp Unofficial (whatsmeow). Pilih method = text untuk mesej bebas, atau method = template untuk hantar template yang telah disediakan di panel.
https://api.cshub.id/api/v1/integration/whatsapp/send-message
Pengesahan
Local API Key di body (`api_key`)
Had kadar
Per-peranti (ikut had daily_send peranti)
Medan body
Body dalam format JSON. Medan di bawah parity dengan whatscrmhub Laravel — migrasi dari versi lama, bentuk permintaan adalah sama.
| Field | Type | Required | Penerangan |
|---|---|---|---|
| api_key | string | ✅ | Local API Key per-perniagaan (UUID). Dapat dari Settings dalam panel cshub. |
| phone | string | ✅ | Nombor penerima format antarabangsa tanpa "+" (cth. 60123456789), atau JID kumpulan apabila `is_group` = true. |
| method | string | ✅ | text, template |
| text | string | method=text | Isi mesej. Wajib apabila method = text. |
| template | string | method=template | ID Message Template yang telah dicipta dalam panel cshub. Wajib apabila method = template. |
| variables | object | — | Objek literal `{placeholder: value}` untuk substitusi template. Contoh: `{"$name":"Budi"}` menggantikan setiap `$name` dalam mesej template dengan "Budi". |
| device_key | string | bergantung * | UUID peranti WhatsApp untuk menghantar. |
| is_group | boolean | — | Set true jika `phone` adalah JID kumpulan (cth. 120363...@g.us). |
Contoh permintaan
1. Hantar mesej teks ringkas
curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
-H "Content-Type: application/json" \
-d '{
"api_key": "<LOCAL_API_KEY>",
"device_key": "<DEVICE_ID>",
"phone": "6281234567890",
"method": "text",
"text": "Halo, makasih udah order ya!"
}'2. Hantar template dengan substitusi variable
curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
-H "Content-Type: application/json" \
-d '{
"api_key": "<LOCAL_API_KEY>",
"device_key": "<DEVICE_ID>",
"phone": "6281234567890",
"method": "template",
"template": "<TEMPLATE_ID>",
"variables": {
"$name": "Pak Budi",
"$order_id": "INV-20260602-001"
}
}'3. Hantar ke kumpulan (guna JID kumpulan)
curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
-H "Content-Type: application/json" \
-d '{
"api_key": "<LOCAL_API_KEY>",
"device_key": "<DEVICE_ID>",
"phone": "120363012345678901@g.us",
"method": "text",
"text": "Pengumuman: order minggu ini ditutup pukul 17:00.",
"is_group": true
}'Respons berjaya (200 OK)
{
"status": true,
"message": "berhasil mengirim pesan"
}Kod ralat & penyelesaian
| Status | Punca | Penyelesaian |
|---|---|---|
| 401 | Api Key Cannot be recognized | Sahkan api_key betul (salin semula dari panel) dan perniagaan tidak digantung. |
| 401 | Device tidak di temukan | Sahkan device_key sah dan peranti aktif. Pasangkan semula peranti melalui QR/kod pasangan di panel jika perlu. |
| 401 | Template tidak dikenali | Sahkan ID template betul dan milik perniagaan anda (senarai template di panel → Master Data → Templates). |
| 422 | Daily send limit habis | Tunggu reset harian (00:00 WIB) atau guna peranti lain. Naikkan limit_per_day di settings peranti jika perlu. |
| 422 | Validation gagal (phone/method/text) | Pastikan phone format antarabangsa tanpa "+" dan method salah satu dari text/template. |
| 502 | WhatsApp service unavailable | WhatsApp service sedang turun. Cuba semula beberapa minit lagi atau semak status peranti di panel. |
Nota & had
- Ada had daily_send per peranti. Elak blast > 10 mesej/saat dari satu peranti untuk elak banned WhatsApp.
- Jika settings perniagaan anda set `api_device_use = required`, medan `device_key` adalah wajib. Jika optional, pelayan auto-pick peranti aktif berdasarkan settings `whatsapp_sender_notif` (`sequence` / `spin` / `random`).
- Substitusi variable menggunakan literal `str_replace` — placeholder boleh apa-apa string (cth. `$name`, `{name}`, `[NAME]`). Yang penting persis sama dengan teks dalam mesej template.
- Sentiasa format tanpa "+" dan tanpa ruang/sengkang. Contoh: 60123456789 (Malaysia), 6281234567890 (Indonesia). Untuk kumpulan: guna JID penuh dengan akhiran `@g.us`.
- Iterasi MVP: muat naik fail binari melalui multipart/form-data belum disokong. Untuk hantar media, guna method=template dengan template yang sudah ada imej di-setup dari panel.
Integration API vs Internal Panel API
cshub mempunyai dua laluan send-message yang sengaja dipisahkan. Integration API untuk pembangun pihak ketiga / automasi; Internal API untuk panel web + aplikasi mudah alih cshub. Audien berbeza, pengesahan berbeza, bentuk respons berbeza.
| Integration API | API Panel Dalaman | |
|---|---|---|
| Audien | Pembangun backend, Zapier, n8n, integrasi tersuai | Panel web cshub-fe, aplikasi cshub-mobile |
| URL | /integration/whatsapp/send-message | /app/device/{id}/chats/send |
| Pengesahan | api_key di body | JWT Bearer + X-Business-ID + CSRF |
| Bentuk respons | {status, message} | {success, message, data} |
Sedia untuk integrasi?
Log masuk ke panel cshub, ambil Local API Key dari Settings, dan mulakan integrasi WhatsApp ke sistem anda.