Platform ini menyediakan REST API publik yang memungkinkan integrasi dengan sistem lain. API bisa digunakan untuk mengirim pesan, mengelola kontak, mengambil data percakapan, dan banyak lagi.

Dokumentasi interaktif dengan Swagger UI tersedia di /docs/api/v1.

---

Autentikasi

Semua request ke API publik membutuhkan autentikasi menggunakan Bearer Token.

Authorization: Bearer wa_pk_xxxxxxxxxxxxxxxxxxxxxxxx

Token dapat dibuat di Pengaturan > API Token. Setiap token bisa diberi nama dan bisa dicabut kapan saja. Token dimulai dengan prefix wa_pk_.

Jaga kerahasiaannya. Token API memberikan akses penuh ke data organisasi kamu. Jangan simpan di repository publik, jangan expose di frontend, dan rotasi secara berkala sebagai praktik keamanan yang baik.

---

Base URL

https://orqestra.id/api/v1

---

Endpoint Tersedia

Kontak

Buat atau perbarui kontak

POST /contacts

Membuat kontak baru. Jika nomor WhatsApp sudah ada, data diperbarui (upsert).

Request body:

{
  "waId": "6281234567890",
  "name": "Budi Santoso",
  "email": "budi@contoh.com",
  "tags": ["pelanggan-vip", "jakarta"]
}

---

Ambil kontak berdasarkan nomor

GET /contacts/:waId

---

Daftar kontak

GET /contacts?page=1&limit=50&tag=pelanggan-vip

---

Pesan

Kirim pesan teks

POST /messages/text

Request body:

{
  "waId": "6281234567890",
  "text": "Halo! Order kamu dengan ID #12345 sudah kami proses.",
  "channelId": "optional-channel-id"
}

Catatan: endpoint ini hanya bisa digunakan dalam jendela 24 jam setelah pesan terakhir dari pelanggan. Di luar jendela tersebut, gunakan endpoint template.

---

Kirim template pesan

POST /messages/template

Request body:

{
  "waId": "6281234567890",
  "templateName": "order_shipped",
  "languageCode": "id",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Budi" },
        { "type": "text", "text": "#12345" },
        { "type": "text", "text": "JNE REG" }
      ]
    }
  ]
}

---

Kirim gambar

POST /messages/image

Request body:

{
  "waId": "6281234567890",
  "imageUrl": "https://cdn.kamu.com/gambar-produk.jpg",
  "caption": "Produk terbaru kami!"
}

---

Percakapan

Daftar percakapan

GET /chats?status=open&page=1&limit=20

Parameter opsional:

• status — open, resolved, atau semua jika tidak diisi
• channel — WHATSAPP atau INSTAGRAM
• channelId — filter by specific channel instance

---

Detail percakapan

GET /chats/:chatId

---

Riwayat pesan dalam percakapan

GET /chats/:chatId/messages?before=messageId&limit=50

---

Broadcast

Buat broadcast

POST /broadcasts

Request body:

{
  "name": "Promo Mei 2025",
  "channelId": "channel-id",
  "templateName": "promo_may",
  "languageCode": "id",
  "recipients": [
    {
      "waId": "6281234567890",
      "variables": ["Budi", "PROMO25"]
    }
  ]
}

---

Status broadcast

GET /broadcasts/:broadcastId

---

Format Response

Semua response menggunakan format JSON dengan struktur konsisten:

Sukses:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 243
  }
}

Error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "waId is required"
  }
}

---

HTTP Status Codes

Code	Keterangan
200	Berhasil
201	Resource berhasil dibuat
400	Request tidak valid (missing field, format salah)
401	Token tidak valid atau tidak ada
403	Token tidak punya akses ke resource ini
404	Resource tidak ditemukan
422	Validasi gagal dengan detail error
429	Rate limit terlampaui
500	Server error

---

Rate Limiting

API dibatasi 100 request per menit per token. Jika terlampaui, server mengembalikan HTTP 429 dengan header:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714000000

Tunggu hingga timestamp di X-RateLimit-Reset sebelum mengirim request berikutnya.

---

Webhook ke Sistem Kamu

Selain menerima request dari sistem kamu, platform juga bisa mendorong event ke sistem eksternal menggunakan outbound webhook.

Konfigurasi di Pengaturan > Webhook Outbound. Event yang tersedia:

• message.received — pesan baru masuk dari pelanggan
• message.sent — pesan berhasil dikirim
• chat.created — percakapan baru dibuat
• chat.assigned — percakapan ditugaskan ke agen
• chat.resolved — percakapan ditutup

Payload setiap event dikirim sebagai POST request ke URL yang kamu tentukan, dengan signature HMAC-SHA256 di header X-Webhook-Signature untuk verifikasi keasliannya.

---

SDK dan Library

Saat ini belum ada SDK resmi yang diterbitkan. Namun API ini dirancang untuk mudah diintegrasikan menggunakan library HTTP standar di bahasa apapun — Node.js (axios, fetch), Python (httpx, requests), PHP (Guzzle), atau lainnya.

Untuk contoh penggunaan dalam berbagai bahasa, lihat halaman Contoh Integrasi di dokumentasi.