Skip to content
S SiPesan Docs
ID EN

API, Testing & Kode Error

Autentikasi

Base URL https://sipesan.com/api/v1/business

Setiap permintaan wajib menyertakan dua header autentikasi:

  • Client-Key — Public Key — Header Client-Key berisi Public Key Anda (diawali pk_). Header ini mengidentifikasi akun API Anda. Boleh dianggap publik.
  • Authorization — Secret Key — Header Authorization berisi Secret Key Anda (diawali sk_) — TANPA kata "Bearer". Rahasiakan key ini; jangan pernah ditaruh di kode frontend.
Client-Key: pk_your_public_key
Authorization: sk_your_secret_key
Content-Type: application/json

Cara mendapatkan key: Buka panel bisnis → grup menu Developers → API Access. Di sana Anda melihat Public Key (pk_…) dan Secret Key (sk_…). Jika belum ada, buat API Access baru.

Cara Mendapatkan channel_id

Parameter channel_id menentukan channel pengirim. Setiap channel punya Channel ID unik yang bisa Anda salin dari panel bisnis:

Channel Cara mendapatkan Channel ID
WhatsApp Panel bisnis → menu WhatsApp Channels. Pada baris channel yang dituju, klik nilai kolom Channel ID untuk menyalinnya.
WhatsApp Web (QR) Panel bisnis → menu WhatsApp Web. Channel harus berstatus Connected. Klik nilai kolom Channel ID pada channel yang dituju untuk menyalinnya — ini dipakai sebagai channel_id pada endpoint /waweb/broadcasts.
Telegram Panel bisnis → menu Telegram Channels. Klik nilai kolom Channel ID pada channel yang dituju untuk menyalinnya.
Instagram Panel bisnis → menu Instagram Channels. Klik nilai kolom Channel ID pada channel yang dituju untuk menyalinnya.

Daftar Endpoint

POST /api/v1/business/messages/send

POST /api/v1/business/messages/send

Kirim pesan ke pelanggan lewat channel yang sudah dikonfigurasi (WhatsApp, Telegram, dll). Mendukung pesan teks dan template rich media.

Autentikasi: Client-Key + Authorization

Parameter

Nama Tipe Keterangan
channel_id Wajib string UUID channel pengirim.
to Wajib string Nomor telepon tujuan (dengan kode negara) atau Customer ID.
message_body string Isi teks pesan. Dipakai untuk pesan teks biasa.
message_components object Untuk mengirim template. Wajib berisi template_name dan opsional template_parameters.

Pesan teks

bash 
curl --location 'https://chat.sipesan.com/api/v1/business/messages/send' \
  --header 'Client-Key: pk_your_public_key' \
  --header 'Authorization: sk_your_secret_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "channel_id": "a0da9833-97a2-4df8-9ef2-22ca0a97362b",
    "to": "6285274784558",
    "message_body": "Halo, pesanan Anda sudah dikirim."
  }'

Pesan template (WhatsApp)

json 
{
  "channel_id": "a0da9833-97a2-4df8-9ef2-22ca0a97362b",
  "to": "6285274784558",
  "message_components": {
    "template_name": "pengiriman_paket",
    "template_parameters": {
      "header": {
        "type": "IMAGE",
        "image": { "link": "https://example.com/image.png" }
      },
      "body": [
        { "type": "text", "text": "pelanggan" },
        { "type": "text", "text": "JNE" },
        { "type": "text", "text": "airways1234656" }
      ]
    }
  }
}

Contoh Respons

201 
{
  "message": "Message is being processed",
  "data": {
    "id": "e145f8a2-...",
    "phone_number": "6285274784558",
    "status": "pending"
  }
}

POST /api/v1/business/broadcasts

POST /api/v1/business/broadcasts

Buat broadcast template WhatsApp. id yang dikembalikan dipakai sebagai broadcast_id saat mengirim pesan per penerima.

Autentikasi: Client-Key + Authorization

Parameter

Nama Tipe Keterangan
name Wajib string Nama broadcast.
channel_id Wajib string UUID channel WhatsApp.
template_name Wajib string Nama template WhatsApp yang sudah APPROVED.
template_language string Kode bahasa template, mis. id / en_US.
template_category string Kategori template (MARKETING/UTILITY).
template_parameters object Parameter default template.

Buat broadcast

bash 
curl --location 'https://chat.sipesan.com/api/v1/business/broadcasts' \
  --header 'Client-Key: pk_your_public_key' \
  --header 'Authorization: sk_your_secret_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Promo Juni",
    "channel_id": "a0da9833-97a2-4df8-9ef2-22ca0a97362b",
    "template_name": "promo_juni",
    "template_language": "id",
    "template_category": "MARKETING"
  }'

Contoh Respons

201 
{
  "data": {
    "id": "8d7c0b1e-...",
    "name": "Promo Juni",
    "template_name": "promo_juni",
    "template_category": "MARKETING",
    "status": "draft",
    "created_at": "2026-06-05T12:00:00.000000Z"
  },
  "message": "Broadcast created. Use the id as broadcast_id when sending messages."
}

GET /api/v1/business/broadcasts/{broadcastId}

GET /api/v1/business/broadcasts/{broadcastId}

Ambil status dan statistik pengiriman sebuah broadcast.

Autentikasi: Client-Key + Authorization

Parameter

Nama Tipe Keterangan
broadcastId Wajib string UUID broadcast (path parameter).

Cek status

bash 
curl --location 'https://chat.sipesan.com/api/v1/business/broadcasts/8d7c0b1e-...' \
  --header 'Client-Key: pk_your_public_key' \
  --header 'Authorization: sk_your_secret_key'

Contoh Respons

200 
{
  "data": {
    "id": "8d7c0b1e-...",
    "name": "Promo Juni",
    "template_name": "promo_juni",
    "status": "sending",
    "total_recipients": 1200,
    "sent_count": 800,
    "delivered_count": 760,
    "read_count": 540,
    "replied_count": 32,
    "failed_count": 8
  }
}

POST /api/v1/business/waweb/broadcasts

POST /api/v1/business/waweb/broadcasts

Kirim broadcast lewat kanal WhatsApp Web (QR). Pengiriman di-pace otomatis (anti-blokir): satu pesan per jeda acak, dengan batas per jam/harian + jam kerja/warmup opsional. Hanya teks (v1), gratis. Spintax {a|b} didukung untuk variasi pesan.

Autentikasi: Client-Key + Authorization

Parameter

Nama Tipe Keterangan
channel_id Wajib string UUID kanal WhatsApp Web yang berstatus connected.
message Wajib string Isi pesan teks. Mendukung spintax {a|b} untuk variasi.
recipients Wajib array<string> Daftar nomor tujuan (format bebas, dinormalisasi & dedup otomatis).
name string Nama broadcast (opsional).

Kirim broadcast WA Web

bash 
curl --location 'https://chat.sipesan.com/api/v1/business/waweb/broadcasts' \
  --header 'Client-Key: pk_your_public_key' \
  --header 'Authorization: sk_your_secret_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "channel_id": "a0da9833-97a2-4df8-9ef2-22ca0a97362b",
    "name": "Promo Juni",
    "message": "{Halo|Hai} kak, ada promo Juni nih!",
    "recipients": ["628111111111", "628222222222"]
  }'

Contoh Respons

201 
{
  "data": {
    "id": "8d7c0b1e-...",
    "status": "sending",
    "total_recipients": 2,
    "created_at": "2026-06-19T12:00:00.000000Z"
  },
  "message": "WA-Web broadcast accepted and sending (paced)."
}

GET /api/v1/business/waweb/broadcasts/{broadcastId}

GET /api/v1/business/waweb/broadcasts/{broadcastId}

Ambil status & statistik pengiriman broadcast WhatsApp Web (terkirim/delivered/dibaca/gagal). Status delivered & read juga dikirim real-time ke webhook delivery-status Anda.

Autentikasi: Client-Key + Authorization

Parameter

Nama Tipe Keterangan
broadcastId Wajib string UUID broadcast (path parameter).

Cek status

bash 
curl --location 'https://chat.sipesan.com/api/v1/business/waweb/broadcasts/8d7c0b1e-...' \
  --header 'Client-Key: pk_your_public_key' \
  --header 'Authorization: sk_your_secret_key'

Contoh Respons

200 
{
  "data": {
    "id": "8d7c0b1e-...",
    "status": "sending",
    "total_recipients": 2,
    "sent_count": 1,
    "delivered_count": 1,
    "read_count": 0,
    "failed_count": 0,
    "started_at": "2026-06-19T12:00:00.000000Z",
    "completed_at": null
  }
}

Kode Error

Status Code Arti Kapan
401 unauthenticated Token tidak valid atau tidak ada. Header Authorization salah atau token kedaluwarsa.
403 forbidden Tidak punya izin untuk resource ini. Akses lintas-tenant atau role tidak cukup.
404 not_found Resource tidak ditemukan. ID salah atau milik bisnis lain.
422 validation_error Input gagal validasi. Body berisi {message, errors:{field:[...]}}.
429 too_many_requests Melebihi rate limit. Lihat header Retry-After.
500 server_error Kesalahan tak terduga di server. Cek log; hubungi support bila berulang.
0 ai_provider_not_configured Provider AI belum dikonfigurasi (internal). AiProviderException::notConfigured() — API key kosong.