Ringkasan
Integration API cshub adalah jalur external untuk kirim pesan WhatsApp dari backend / automation tool kamu. Pakai Local API Key per business untuk auth (mirror behavior whatscrmhub Laravel). Endpoint ini terpisah dari endpoint internal yang dipakai panel + mobile app cshub.
Base URL
https://api.cshub.id/api/v1
Content-Type
application/json
Autentikasi
Auth pakai Local API Key di body request (field `api_key`), bukan HTTP header. Setiap business punya 1 Local API Key (UUID) yang di-generate otomatis saat business dibuat.
Tidak ada JWT, tidak ada header token
Beda dari endpoint internal panel. Cukup kirim `api_key` di body, server resolve business dari sana. Untuk keamanan, treat Local API Key seperti password — jangan commit ke repo publik, jangan expose di frontend.
Cara dapat Local API Key
- Login ke panel cshub di /app.
- Buka menu Settings → API Key (atau Profile → Integration).
- Copy Local API Key. Bisa regenerate kapan saja (yang lama langsung invalid).
Endpoint
Satu endpoint untuk semua jenis pesan WhatsApp Unofficial (whatsmeow). Pilih method = text untuk pesan bebas, atau method = template untuk pesan dari template yang sudah dibuat di panel.
https://api.cshub.id/api/v1/integration/whatsapp/send-message
Auth
Local API Key di body (`api_key`)
Rate limit
Per-device (sesuai daily_send limit device)
Field body
Body request dalam format JSON. Field di bawah ini parity dengan whatscrmhub Laravel — kalau kamu migrasi dari versi lama, request shape-nya identik.
| Field | Type | Required | Deskripsi |
|---|---|---|---|
| api_key | string | ✅ | Local API Key business (UUID). Dapat dari Settings panel cshub. |
| phone | string | ✅ | Nomor tujuan format internasional tanpa "+" (mis. 6281234567890), atau group JID kalau `is_group` = true. |
| method | string | ✅ | text, template |
| text | string | method=text | Isi pesan text. Wajib bila method = text. |
| template | string | method=template | ID Message Template yang sudah dibuat di panel cshub. Wajib bila method = template. |
| variables | object | — | Object literal `{placeholder: value}` untuk substitusi di template. Contoh: `{"$name":"Budi"}` akan replace semua `$name` di template message dengan "Budi". |
| device_key | string | tergantung * | UUID device WhatsApp yang akan dipakai kirim. |
| is_group | boolean | — | Set true kalau `phone` adalah group JID (mis. 120363...@g.us). |
Contoh request
1. Kirim pesan text simple
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. Kirim pesan template dengan variable substitusi
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. Kirim ke group (pakai group JID)
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
}'Response sukses (200 OK)
{
"status": true,
"message": "berhasil mengirim pesan"
}Error code & solusi
| Status | Penyebab | Solusi |
|---|---|---|
| 401 | Api Key Cannot be recognized | Cek api_key benar (copy ulang dari panel) dan business belum di-suspend. |
| 401 | Device tidak di temukan | Cek device_key valid + device dalam status active. Login ulang device via QR/pair code di panel kalau perlu. |
| 401 | Template tidak dikenali | Cek template ID benar dan milik business kamu (template = lihat list di panel → Master Data → Templates). |
| 422 | Daily send limit habis | Tunggu reset harian (00:00 WIB) atau pakai device lain. Naikkan limit_per_day di settings device kalau perlu. |
| 422 | Validation gagal (phone/method/text) | Pastikan phone format internasional tanpa "+" dan method salah satu dari text/template. |
| 502 | WhatsApp service unavailable | WhatsApp service sedang down. Retry beberapa menit lagi atau cek status device di panel. |
Catatan & batasan
- Ada daily_send limit per device. Hindari blast > 10 pesan/detik dari satu device untuk hindari banned WhatsApp.
- Kalau settings business kamu set `api_device_use = required`, field `device_key` WAJIB diisi. Kalau set optional, server akan auto-pick device active sesuai strategi (`sequence` / `spin` / `random` di settings `whatsapp_sender_notif`).
- Substitusi variable pakai literal `str_replace` — placeholder bisa berupa string apapun (mis. `$name`, `{name}`, `[NAME]`). Yang penting persis sama dengan yang ada di template message.
- Selalu format tanpa "+" dan tanpa spasi/strip. Contoh: 6281234567890 (Indonesia), 60123456789 (Malaysia). Untuk group: gunakan full JID dengan suffix `@g.us`.
- Iterasi MVP: belum support upload file binary via multipart/form-data. Untuk kirim media, pakai method=template dengan template yang sudah punya image di-setup dari panel.
Integration API vs Internal Panel API
cshub punya dua jalur send-message yang sengaja dipisah. Integration API untuk developer 3rd party / automation; Internal API untuk panel web + mobile app cshub. Beda audience, beda auth, beda response shape.
| Integration API | Internal Panel API | |
|---|---|---|
| Audience | Backend developer, Zapier, n8n, custom integration | Panel web cshub-fe, mobile app cshub-mobile |
| URL | /integration/whatsapp/send-message | /app/device/{id}/chats/send |
| Auth | api_key di body | JWT Bearer + X-Business-ID + CSRF |
| Response shape | {status, message} | {success, message, data} |
Siap integrasi?
Login ke panel cshub, ambil Local API Key dari Settings, dan langsung integrasi WhatsApp ke sistem kamu.