MSGly
Mulai Sekarang
Developer Portal & Official SDKs

MSGly WhatsApp API Documentation

Panduan integrasi resmi REST API dan Official SDKs (Node.js, Go, Python, PHP, Java) untuk WhatsApp OTP dengan rotasi template otomatis, WhatsApp Blast, dan Webhook real-time delivery callback.

Getting Started

MSGly menyediakan REST API berkecepatan tinggi dengan autentikasi berbasis standar industri OAuth 2.0 (Client Credentials). Pengiriman pesan didukung oleh cluster antrean Redis asinkron dan device pool WhatsApp yang berputar secara dinamis (round-robin).

Konfigurasi Nilai Produksi
Production Base URL https://api.msgly.id/api/v1
Otentikasi OAuth 2.0 (Bearer Token via Client Credentials)
Format Data JSON (Request Body & Response), URL-Encoded (OAuth Token)
ID Idempotency xid (Wajib unik per transaksi pengiriman)

Alur Persiapan Integrasi

  1. Login ke Dashboard MSGly: Akses dashboard.msgly.id dengan akun Client Anda.
  2. Buat API Client: Masuk ke menu API Client di sidebar, lalu klik Create New API Client. Masukkan nama aplikasi dan daftarkan Webhook URL (opsional) untuk callback status delivery.
  3. Simpan Kredensial: Salin client_id dan client_secret Anda. Pastikan menyimpannya di environment variable backend.
  4. Request Access Token: Tukar Client ID & Secret dengan Bearer Token melalui endpoint POST /api/v1/oauth/token.
  5. Kirim Pesan: Kirim WhatsApp OTP atau pesan tunggal melalui endpoint POST /api/v1/message.
Keamanan Kredensial: Jangan pernah menyimpan client_secret pada kode frontend (React, Vue, mobile apps, atau browser scripts). Seluruh interaksi dengan API MSGly wajib dilakukan dari server/backend Anda.

Authentication (OAuth 2.0)

MSGly menggunakan grant type client_credentials. Kredensial client_id dan client_secret ditukarkan dengan Access Token yang berlaku selama 24 jam (86.400 detik).

POST https://api.msgly.id/api/v1/oauth/token

Mendapatkan access token Bearer untuk otentikasi request berikutnya.

Request Header & Body (application/x-www-form-urlencoded):

ParameterTipeWajibDeskripsi
grant_typestringWajibHarus bernilai tepat client_credentials
client_idstringWajibClient ID yang diterbitkan dari Dashboard MSGly
client_secretstringWajibClient Secret yang diterbitkan dari Dashboard MSGly
cURL Request Example
curl -X POST https://api.msgly.id/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
Response (200 OK)
{
  "success": true,
  "message": "token issued",
  "data": {
    "access_token": "msgly_tk_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}
Best Practice Token Caching: Token yang diterbitkan berlaku selama 24 jam. Sangat disarankan untuk menyimpan (cache) token di memori atau Redis backend Anda, dan hanya me-refresh token baru jika token kedaluwarsa (HTTP 401). Hindari memanggil /oauth/token pada setiap pengiriman pesan agar tidak terkena rate limit.

Kirim Pesan (/message)

Pengiriman pesan WhatsApp API eksternal dikirimkan melalui endpoint terpadu POST /api/v1/message. Layanan yang didukung meliputi WhatsApp OTP, WhatsApp Notification, WhatsApp Reminder (langsung / terjadwal), serta Single Message. Sistem akan otomatis memilih WhatsApp device yang aktif dari pool akun dan meng-enqueue pesan ke dalam antrean Redis dengan prioritas tinggi.

Catatan Service Policy: Layanan notification, reminder, dan single dapat dikonfigurasi aktif/nonaktif melalui dashboard admin. Pengiriman pesan promosi/broadcast massal tetap dilayani melalui fitur WhatsApp Blast di Dashboard.
POST https://api.msgly.id/api/v1/message

Parameter Request (JSON Body):

FieldTipeWajibKeterangan
xid string Wajib ID unik transaksi Anda (Idempotency Key). Menjamin tidak ada pesan ganda terkirim saat terjadi retry jaringan.
to string Wajib Nomor WhatsApp tujuan dalam format internasional (contoh: 628123456789). Awalan lokal 08... otomatis dinormalkan sistem ke 628....
type string Wajib Pilihan tipe pesan: otp, notification, reminder, atau single.
message string Opsional* Teks pesan bebas langsung (wajib jika tidak menggunakan template pada notifikasi/reminder/single).
code string Opsional (OTP) Kode OTP angka/alfanumerik untuk mode rotasi OTP otomatis oleh server.
template object Opsional* Objek template spesifik { "template_id": "UUID", "params": ["..."] } bila memilih pengiriman berbasis template berparameter.
scheduled_at string Opsional (Reminder) Waktu pengiriman terjadwal dalam format ISO 8601 / RFC3339 (contoh: 2026-09-25T09:00:00Z). Jika kosong atau waktu lampau, pesan dikirim saat itu juga.
Response Format (200 OK)
{
  "messages": {
    "id": "7c4817a5-d85c-48c0-845f-c9ab579899eb",
    "xid": "trx-unique-001",
    "status": "queued",
    "timestamp": 1718451123456
  }
}
Asynchronous Processing & Message ID: Respon HTTP awal langsung mengembalikan status queued beserta id (MSGly Message UUID) dalam waktu < 50ms. Status delivery lanjutan (sent, delivered, read, failed) dan WhatsApp Message ID (oid) akan dikirimkan secara asinkron melalui Webhook Callback.

WhatsApp OTP

Pengiriman kode verifikasi OTP WhatsApp dirancang dengan latensi minimal dan tingkat pengiriman tinggi. MSGly mendukung dua skenario integrasi:

Skenario A: OTP Template Rotation (Direkomendasikan)

Jika fitur OTP Rotation diaktifkan untuk akun Anda di Dashboard, server MSGly secara dinamis memilih template pesan acak dari template yang telah di-whitelist. Anda cukup mengirimkan nomor tujuan dan kode OTP-nya saja. Cara ini terbukti paling efektif menjaga performa nomor sender dari deteksi spam WhatsApp.

POST /api/v1/message (OTP Rotation)
{
  "xid": "otp-trx-993",
  "to": "628123456789",
  "type": "otp",
  "code": "482019"
}

Skenario B: Manual Template Selection

Jika Anda perlu menggunakan template tertentu (misalnya template login khusus atau registrasi tertentu), sertakan UUID template_id dan array params.

POST /api/v1/message (Manual Template)
{
  "xid": "otp-trx-992",
  "to": "628123456789",
  "type": "otp",
  "template": {
    "template_id": "c8f7a1b2-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "params": ["482019"]
  }
}

WhatsApp Notification

Layanan WhatsApp Notification dirancang khusus untuk pengiriman pesan transaksional dan operasional, seperti status pesanan, notifikasi pembayaran sukses, konfirmasi booking, atau perubahan akun. Layanan ini mendukung pendekatan Hybrid fleksibel:

1. Pengiriman Teks Langsung (Direct Message)

Kirimkan notifikasi langsung berupa teks bebas tanpa perlu membuat template di dashboard:

POST /api/v1/message (Direct Notification)
{
  "xid": "notif-trx-1001",
  "to": "628123456789",
  "type": "notification",
  "message": "Halo Budi, pembayaran invoice #INV-2049 telah berhasil dikonfirmasi. Terima kasih!"
}

2. Pengiriman Berbasis Template (Template with Parameters)

Gunakan template yang telah terdaftar dan approved di akun Anda untuk keseragaman format:

POST /api/v1/message (Template Notification)
{
  "xid": "notif-trx-1002",
  "to": "628123456789",
  "type": "notification",
  "template": {
    "template_id": "c8f7a1b2-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "params": ["Budi", "INV-2049", "Lunas"]
  }
}

WhatsApp Reminder

Layanan WhatsApp Reminder memudahkan pengiriman pesan pengingat jatuh tempo, janji temu (appointment), jadwal konsultasi, maupun jadwal webinar. Mendukung pengiriman langsung maupun penjadwalan otomatis (Scheduled Delivery).

Penjadwalan Terjadwal (Scheduled Reminder)

Sertakan field scheduled_at dengan format ISO 8601 / RFC3339 (misal: 2026-09-25T10:00:00Z). Worker antrean asinkron MSGly akan menahan pesan dan mengeksekusinya secara presisi pada waktu yang ditentukan.

POST /api/v1/message (Scheduled Reminder)
{
  "xid": "rem-trx-2001",
  "to": "628123456789",
  "type": "reminder",
  "message": "Pengingat: Jadwal janji temu dokter Anda akan berlangsung besok pukul 10:00 WIB di RS Mitra Sehat.",
  "scheduled_at": "2026-09-25T10:00:00Z"
}
Response (Status Scheduled)
{
  "messages": {
    "id": "9d8e7f6a-1234-5678-9abc-def012345678",
    "xid": "rem-trx-2001",
    "status": "scheduled",
    "timestamp": 1758794400000
  }
}
Catatan: Sama seperti Notification, Reminder juga mendukung pengiriman berbasis template berparameter dengan menyertakan objek template: { "template_id": "...", "params": [...] }.

WhatsApp Blast (Campaign)

Untuk pengiriman pesan promosi dan broadcast massal ke ribuan kontak sekaligus, MSGly menyediakan Campaign Blast Engine terintegrasi di Dashboard MSGly:

Fitur Proteksi BlastMekanisme Kerja
Device Pool Auto-Distribution Daftar penerima campaign didistribusikan secara round-robin ke seluruh device WhatsApp yang terhubung di pool akun Anda, menjaga beban kirim per device tetap seimbang.
Dynamic Throttling & Delays Jeda antar pesan diacak (randomized interval delay) untuk menghindari pola pengiriman bot yang mencurigakan bagi WhatsApp.
Chat Presence Simulation Worker otomatis mengirimkan sinyal composing (mengetik) beberapa detik sebelum pesan dikirimkan, mensimulasikan perilaku pengguna manusia asli.
Realtime Stop & Pause Campaign dapat dipause, dibatalkan, atau dijadwalkan secara real-time langsung melalui dashboard.
Untuk melakukan blast campaign skala besar, Anda dapat mengimpor kontak melalui file CSV di menu Contacts > Import CSV pada Dashboard Client, lalu membuat campaign di menu Campaigns.

Webhooks & Delivery Status

Daftarkan Webhook URL pada pengaturan API Client Anda untuk menerima notifikasi callback secara real-time saat status pesan berubah.

Siklus Status Pengiriman (Delivery Lifecycle)

  • queued: Pesan berhasil diterima oleh API dan masuk ke antrean worker Redis.
  • sent: Pesan berhasil dikirimkan oleh device WhatsApp gateway ke server WhatsApp.
  • delivered: Pesan telah sampai di perangkat penerima (centang dua abu-abu).
  • read: Pesan telah dibuka dan dibaca oleh penerima (centang dua biru).
  • failed: Pesan gagal terkirim (misal: nomor tujuan tidak terdaftar di WhatsApp atau device gateway offline).
Webhook Payload Example (POST ke URL Anda)
{
  "event": "message.status",
  "data": {
    "id": "7c4817a5-d85c-48c0-845f-c9ab579899eb",
    "xid": "trx-unique-001",
    "recipient": "628123456789",
    "status": "delivered",
    "oid": "3EB0B892819024D98A",
    "timestamp": 1718451125000,
    "error": ""
  }
}
Kebijakan Retry Callback: Server MSGly akan mencoba mengirimkan ulang webhook hingga 3 kali dengan exponential backoff jika server Anda mengembalikan status HTTP selain 2xx atau terjadi timeout. Pastikan endpoint webhook Anda mengembalikan respon HTTP 200 OK dengan cepat.

Error Codes & Response

Jika terjadi kendala validasi, autentikasi, atau saldo, API akan mengembalikan HTTP status code yang sesuai beserta objek error berformat JSON:

Format Respon Error JSON
{
  "error": {
    "message": "duplicate xid"
  }
}
HTTP StatusPesan ErrorPenyebab & Solusi
400 Bad Request duplicate xid Nilai xid ini sudah pernah digunakan sebelumnya. Gunakan ID unik yang baru untuk setiap transaksi.
400 Bad Request invalid phone number Nomor penerima tidak valid atau memiliki format karakter yang salah.
400 Bad Request insufficient balance Saldo wallet akun Anda tidak mencukupi untuk memproses pengiriman pesan. Lakukan topup saldo melalui dashboard.
400 Bad Request template not found UUID template_id yang dikirim tidak ditemukan atau belum disetujui.
400 Bad Request WhatsApp Notification service is currently disabled by administrator. Layanan WhatsApp Notification sedang dinonaktifkan di pengaturan sistem oleh administrator.
400 Bad Request WhatsApp Reminder service is currently disabled by administrator. Layanan WhatsApp Reminder sedang dinonaktifkan di pengaturan sistem oleh administrator.
400 Bad Request Single message service is currently disabled by administrator. Layanan Single message sedang dinonaktifkan di pengaturan sistem oleh administrator.
401 Unauthorized The access token has expired Access token OAuth 2.0 telah habis masa berlakunya. Lakukan request token baru via /oauth/token.
429 Too Many Requests rate limit exceeded Jumlah request melebihi batas rate limit akun Anda (default: 100 req/menit). Tunggu beberapa saat sebelum mencoba kembali.

Rate Limits

Untuk menjaga kestabilan sistem dan mencegah lonjakan lalu lintas yang tidak wajar, setiap API Client memiliki batasan kecepatan request:

Area EndpointDefault LimitMekanisme Kontrol
POST /api/v1/message 100 request / menit per Client ID Redis distributed rate limiter (Sliding Window). Hubungi tim sales jika aplikasi Anda memerlukan limit throughput lebih besar.
POST /api/v1/oauth/token 20 request / menit per IP Proteksi brute-force token generation. Simpan token selama 24 jam.

Official SDKs & Libraries

MSGly menyediakan pustaka (SDK) resmi untuk mempermudah integrasi ke backend Anda tanpa perlu mengelola OAuth token refresh, serialisasi JSON, ataupun parsing error secara manual.

BahasaPackage ManagerPerintah Instalasi
Node.js (JS/TS) NPM npm install msgly-sdk
Go (Golang) Go Modules go get github.com/msgly-official/msgly-sdk-go
Python PyPI pip install msgly-sdk
PHP Composer composer require msgly/msgly-sdk-php
Java JitPack (Maven / Gradle) com.github.msgly-official:msgly-sdk-java:v1.0.0

Contoh Integrasi Lengkap per Bahasa

Node.js (ESM / CommonJS)
import { MsglyClient } from 'msgly-sdk';

const msgly = new MsglyClient({
  baseUrl: 'https://api.msgly.id', // Opsional, default https://api.msgly.id
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET'
});

// 1. Kirim WhatsApp OTP (Mode Rotasi Otomatis)
try {
  const otpResponse = await msgly.message.sendOTP({
    xid: 'otp_' + Date.now(),
    to: '6281234567890',
    code: '482910'
  });
  console.log('OTP Queued ID:', otpResponse.messages.id);
} catch (error) {
  console.error('Gagal mengirim OTP:', error.message);
}

// 2. Kirim WhatsApp Notification
try {
  const notifResponse = await msgly.message.sendNotification({
    xid: 'notif_' + Date.now(),
    to: '6281234567890',
    message: 'Halo, pesanan Anda #INV-1029 telah selesai diproses.'
  });
  console.log('Notification Queued ID:', notifResponse.messages.id);
} catch (error) {
  console.error('Gagal mengirim notifikasi:', error.message);
}

// 3. Kirim WhatsApp Reminder (Terjadwal)
try {
  const reminderResponse = await msgly.message.sendReminder({
    xid: 'rem_' + Date.now(),
    to: '6281234567890',
    message: 'Pengingat: Jadwal janji temu dokter Anda besok pukul 10:00 WIB.',
    scheduled_at: new Date(Date.now() + 24 * 60 * 60 * 1000)
  });
  console.log('Reminder Queued/Scheduled ID:', reminderResponse.messages.id);
} catch (error) {
  console.error('Gagal mengirim reminder:', error.message);
}

Butuh Bantuan Integrasi atau Custom Setup?

Tim support dan developer engineer MSGly siap mendampingi proses implementasi API dan SDK ke sistem Anda.

Konsultasi Engineer MSGly