Botline Outbound API

REST API untuk mengirim pesan WhatsApp (teks, gambar, video, audio, dokumen) dari aplikasi Anda melalui channel Botline. Cukup satu endpoint, autentikasi Bearer token, format JSON.

Base URL

https://app.botline.id/api/v1

Semua permintaan menggunakan HTTPS, body & respons berformat application/json (UTF-8). Ukuran body maksimal 1 MB.

Akses API tersedia pada paket Bisnis dan Pro. Pada paket lain, endpoint akan menolak dengan kode 403.

Autentikasi

Sertakan API key Anda pada header Authorization di setiap permintaan:

Authorization: Bearer botline_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

API key dibuat dan dikelola di Dashboard → Channel WhatsApp → API Key. Key hanya ditampilkan sekali saat dibuat — simpan di tempat aman.

Perlakukan API key seperti kata sandi. Jangan menaruhnya di kode front-end, repositori publik, atau pesan yang tidak terenkripsi. Jika bocor, segera cabut (revoke) dan buat key baru dari dashboard.

Kirim Pesan

POST https://app.botline.id/api/v1/outbound/send

Header

Header	Wajib	Keterangan
`Authorization`	wajib	`Bearer botline_xxx`
`Content-Type`	wajib	`application/json`
`Idempotency-Key`	opsional	UUID v4 untuk mencegah duplikasi pengiriman (lihat Idempotency)

Field Body

Field	Tipe	Wajib	Keterangan
`whatsapp_account_id`	string	wajib	UUID channel WhatsApp Anda (lihat halaman Channel WhatsApp di dashboard)
`to`	string	wajib	Nomor tujuan format E.164 hanya angka, tanpa tanda `+` (mis. `628123456789`)
`type`	string	wajib	Salah satu: `message`, `image`, `video`, `audio`, `file`
`message`	string	kondisional	Isi teks — wajib jika `type=message`
`image_url`	string	kondisional	URL gambar — wajib jika `type=image`
`video_url`	string	kondisional	URL video — wajib jika `type=video`
`audio_url`	string	kondisional	URL audio — wajib jika `type=audio`
`file_url`	string	kondisional	URL dokumen — wajib jika `type=file` (lihat Catatan Media)
`filename`	string	opsional	Nama file yang ditampilkan untuk `type=file`
`caption`	string	opsional	Teks di bawah media (untuk `image`, `video`, `file`)

Respons Sukses 200 OK

{
  "message_id": "wamid.HBgMN...EXAMPLE",
  "status": "sent"
}

Contoh per Tipe (curl)

Nilai di bawah hanya contoh — ganti dengan API key, whatsapp_account_id, dan data Anda sendiri.

1. Pesan Teks

curl -X POST "https://app.botline.id/api/v1/outbound/send" \
  -H "Authorization: Bearer botline_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to": "628123456789",
    "type": "message",
    "message": "Halo! Pesanan Anda sudah kami terima."
  }'

2. Gambar (dengan caption)

curl -X POST "https://app.botline.id/api/v1/outbound/send" \
  -H "Authorization: Bearer botline_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to": "628123456789",
    "type": "image",
    "image_url": "https://contoh.com/media/promo.jpg",
    "caption": "Promo spesial minggu ini!"
  }'

3. Video

curl -X POST "https://app.botline.id/api/v1/outbound/send" \
  -H "Authorization: Bearer botline_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to": "628123456789",
    "type": "video",
    "video_url": "https://contoh.com/media/tutorial.mp4",
    "caption": "Cara pakai produk kami"
  }'

4. Audio

curl -X POST "https://app.botline.id/api/v1/outbound/send" \
  -H "Authorization: Bearer botline_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to": "628123456789",
    "type": "audio",
    "audio_url": "https://contoh.com/media/voice-note.ogg"
  }'

5. Dokumen / File

curl -X POST "https://app.botline.id/api/v1/outbound/send" \
  -H "Authorization: Bearer botline_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to": "628123456789",
    "type": "file",
    "file_url": "https://contoh.com/media/invoice.pdf",
    "filename": "Invoice-2026.pdf",
    "caption": "Faktur Anda"
  }'

Respons & Kode Error

Bila terjadi kesalahan, respons memakai envelope berikut dengan kode HTTP yang sesuai:

{
  "error": true,
  "message": "keterangan kesalahan"
}

Kode	Arti	Penyebab umum
200	Berhasil	Pesan diterima & diteruskan ke WhatsApp
400	Bad Request	Field wajib kosong, `type` tidak dikenal, atau `whatsapp_account_id` tidak ditemukan / bukan milik Anda
401	Unauthorized	Header Authorization tidak ada/salah, atau API key invalid, nonaktif, atau kedaluwarsa
403	Forbidden	Paket Anda tidak menyertakan akses API (upgrade ke Bisnis/Pro)
429	Too Many Requests	Melewati rate limit — lihat header `Retry-After`
502	Bad Gateway	Gagal mengirim ke WhatsApp (mis. channel tidak aktif/terhubung)
500	Server Error	Kesalahan internal — coba lagi beberapa saat

Rate Limit

Permintaan dibatasi per API key per menit sesuai kuota paket Anda. Saat melewati batas, respons memberi kode 429 beserta header:

Retry-After: 60

Tunggu sesuai Retry-After (detik) sebelum mencoba lagi. Disarankan menerapkan antrian/back-off di sisi aplikasi Anda untuk volume tinggi.

Idempotency

Untuk mencegah pesan terkirim ganda (mis. saat retry karena timeout jaringan), sertakan header Idempotency-Key berisi UUID v4 unik per pesan:

Idempotency-Key: 3f1a9c52-7b84-4e2a-9d10-2c6f8b5a1e90

Gunakan key yang sama saat mengulang permintaan yang sama. Jika header tidak dikirim, sistem membuat key otomatis (tanpa perlindungan duplikasi lintas-percobaan).

Webhook Callback outbound_sent

Jika channel Anda dikonfigurasi dengan URL webhook, Botline mengirim notifikasi POST ke URL tersebut setiap kali pesan berhasil dikirim. Atur URL & secret di Dashboard → Channel WhatsApp → Konfigurasi Webhook.

Payload

{
  "event_type": "outbound_sent",
  "whatsapp_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to": "628123456789",
  "type": "message",
  "message_id": "wamid.HBgMN...EXAMPLE",
  "idempotency_key": "3f1a9c52-7b84-4e2a-9d10-2c6f8b5a1e90",
  "timestamp": "2026-01-01T10:00:00Z",
  "request": { /* salinan request asli */ }
}

Header verifikasi

Header	Keterangan
`X-Botline-Timestamp`	Waktu kirim (Unix epoch detik)
`X-Botline-Signature`	`sha256=<hex>` — HMAC-SHA256 dari raw body memakai webhook secret Anda. Dikirim hanya jika secret dikonfigurasi.

Verifikasi tanda tangan

Hitung HMAC-SHA256 dari body mentah lalu bandingkan dengan header (gunakan perbandingan konstan-waktu).

# Node.js (Express, raw body)
const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
          .update(rawBody)
          .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

# Verifikasi cepat via openssl (ganti SECRET)
cat body.json | openssl dgst -sha256 -hmac "whsec_xxxxxxxxxxxx"
# bandingkan hasilnya dengan nilai setelah "sha256=" pada X-Botline-Signature

Balas webhook dengan status 2xx. Tolak permintaan yang tanda tangannya tidak cocok. Pengiriman webhook bersifat best-effort & tidak memengaruhi respons API kirim pesan.

Catatan Media

Untuk type=image, video, audio: berikan URL media yang dapat diakses publik pada field yang sesuai.
Untuk type=file (dokumen): gunakan URL dari Penyimpanan Botline Anda. URL dari domain lain akan ditolak demi keamanan. Ukuran file maksimal 64 MB.
caption hanya berlaku untuk image, video, dan file.
Nomor to ditulis hanya angka dengan kode negara, tanpa + atau spasi (mis. 628123456789).