pixco

Dokumentasi API

Semua yang kamu butuhkan untuk mengirim pesan WhatsApp secara otomatis dari aplikasimu — dari koneksi device hingga pengiriman pesan bulk.

Base URL/api/v1

Mulai Pakai pixco

Ikuti langkah-langkah ini supaya WhatsApp gateway kamu siap mengirim pesan.

1

Buat Akun & Pilih Paket

Daftar di pixco dan pilih paket yang sesuai: Starter untuk mulai cepat, Basic untuk operasional harian, atau Pro untuk tim dengan volume tinggi.

2

Hubungkan Perangkat WhatsApp

Tambahkan perangkat dari menu Perangkat di dashboard. Scan QR code dengan WhatsApp kamu untuk menghubungkan nomor.

Gunakan nomor WhatsApp yang aktif dan tidak sedang digunakan di perangkat lain.
3

Buat API Key

Buka menu API Keys di dashboard, buat key baru dengan permission yang sesuai. Gunakan API key di header x-api-key.

Simpan license key dengan aman. Jangan taruh di frontend yang bisa diakses publik.
4

Mulai Kirim Pesan

Gunakan endpoint /api/v1/send/message dengan API key kamu untuk mengirim pesan WhatsApp dari aplikasimu.

Referensi API

Endpoint pengiriman pesan menggunakan header x-api-key untuk autentikasi. Endpoint lainnya menggunakan Bearer token.

POST/api/v1/send/messageKirim Pesan

Kirim pesan WhatsApp ke satu nomor tujuan. Gunakan scheduled_at (ISO 8601) untuk menjadwalkan pengiriman di masa depan.

scheduled_at bersifat opsional. Jika tidak diisi, pesan langsung dikirim.
Headers
x-api-keyAPI key dari menu API Keys
Content-Typeapplication/json
Request Body
{
  "device_id": "id-device-dari-get-devices",
  "to": "628123456789",
  "message": "Halo dari pixco!",
  "scheduled_at": "2026-05-20T14:00:00Z"
}
Response
{
  "status": "success",
  "message_id": "uuid-message",
  "to": "628123456789",
  "status_msg": "pending"
}
POST/api/v1/send/bulkKirim Pesan Massal

Kirim pesan ke banyak nomor sekaligus menggunakan satu request.

Headers
x-api-keyAPI key dari menu API Keys
Content-Typeapplication/json
Request Body
{
  "device_id": "id-device-dari-get-devices",
  "targets": [
    "628111111111",
    "628222222222"
  ],
  "message": "Halo dari pixco!"
}
Response
{
  "status": "success",
  "queued": 2
}
GET/api/v1/messagesDaftar Pesan

Ambil riwayat pesan yang dikirim dan diterima. Memerlukan Bearer token.

Headers
AuthorizationBearer <jwt_token>
Response
{
  "data": [],
  "total": 0,
  "page": 1,
  "limit": 20
}
DELETE/api/v1/devices/{id}Hapus Device

Menghapus device dengan alur aman: logout/disconnect session WhatsApp terlebih dahulu, lalu menghapus seluruh riwayat pesan yang berelasi dengan device tersebut secara transaksional.

deleted_messages_count hanya menghitung pesan milik user yang sedang login (scoped by user_id), bukan semua user.
Headers
AuthorizationBearer <jwt_token>
Response
{
  "message": "Deleted successfully",
  "deleted_messages_count": 12,
  "device_logged_out": true
}
GET/api/v1/send/scheduledDaftar Pesan Terjadwal

Ambil daftar pesan yang dijadwalkan. Termasuk yang masih pending dan yang sudah terkirim. Support pagination via query page & limit.

Headers
x-api-keyAPI key dari menu API Keys
Response
{
  "data": [
    {
      "id": "uuid",
      "to": "628xxx",
      "content": "Halo",
      "status": "pending",
      "scheduled_at": "2026-05-20T14:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}
PUT/api/v1/send/scheduled/{id}Ubah Jadwal Pesan

Mengubah waktu jadwal pesan yang sudah ada. Kirim scheduled_at baru untuk reschedule, atau kirim null untuk membatalkan jadwal (pesan tetap tersimpan sebagai draft).

Headers
x-api-keyAPI key dari menu API Keys
Content-Typeapplication/json
Request Body
{
  "scheduled_at": "2026-05-21T10:00:00Z"
}
Response
{
  "status": "success",
  "message_id": "uuid",
  "scheduled_at": "2026-05-21T10:00:00Z"
}
DELETE/api/v1/send/scheduled/{id}Batalkan Jadwal

Membatalkan jadwal pesan. Pesan tetap ada di database tapi jadwal dihapus (scheduled_at = null).

Headers
x-api-keyAPI key dari menu API Keys
Response
{
  "status": "success",
  "message_id": "uuid"
}
PATCH/api/v1/devices/{id}/ai-addonKonfigurasi AI Device

Mengaktifkan/menonaktifkan AI, mengatur provider, model, system prompt, guardrail, dan key source (BYOK atau PixAI) untuk sebuah device.

Body JSON. ai_guardrail_enabled default true. Kosongkan ai_guardrail_prompt untuk menggunakan guardrail bawaan.
Headers
AuthorizationBearer <jwt_token>
Content-Typeapplication/json
Request Body
{
  "ai_enabled": true,
  "ai_provider": "openrouter",
  "ai_model": "google/gemini-2.0-flash-001",
  "ai_use_shared_key": true,
  "ai_fallback_to_chatbot": true,
  "ai_guardrail_enabled": true,
  "ai_guardrail_prompt": "Kamu adalah asisten yang hanya menjawab dari knowledge yang disediakan.",
  "ai_api_key": "sk-xxx"
}
Response
{
  "message": "operation_success",
  "data": {
    "ai_enabled": true,
    "ai_provider": "openrouter",
    "ai_model": "google/gemini-2.0-flash-001",
    "ai_use_shared_key": true,
    "ai_guardrail_enabled": true,
    "ai_guardrail_prompt": "..."
  }
}
GET/api/v1/ai/knowledge?device_id={device_id}Daftar Knowledge

Ambil semua dokumen knowledge untuk sebuah device. Wajib menyertakan device_id sebagai query parameter.

Hasil bisa difilter dengan ?is_active=true/false.
Headers
AuthorizationBearer <jwt_token>
Response
{
  "data": [
    {
      "id": "uuid",
      "title": "Produk Kami",
      "content": "Ini adalah deskripsi produk...",
      "source_type": "text",
      "file_url": null,
      "file_orig_name": null,
      "is_active": true
    }
  ]
}
POST/api/v1/ai/knowledgeTambah Knowledge

Menambahkan dokumen knowledge baru ke device. Bisa berupa teks manual atau upload file (TXT/CSV/PDF, maks 2 MB).

Gunakan Content-Type: multipart/form-data untuk upload file.
Headers
AuthorizationBearer <jwt_token>
Request Body
{
  "device_id": "uuid-device",
  "title": "Produk Kami",
  "content": "Ini adalah deskripsi produk..."
}
Response
{
  "message": "Knowledge created",
  "id": "uuid-knowledge"
}
PUT/api/v1/ai/knowledge/{id}Edit Knowledge

Memperbarui judul, konten, atau status aktif dokumen knowledge.

Headers
AuthorizationBearer <jwt_token>
Content-Typeapplication/json
Request Body
{
  "title": "Produk Kami (Update)",
  "content": "Konten baru...",
  "is_active": true
}
Response
{
  "message": "Knowledge updated"
}
DELETE/api/v1/ai/knowledge/{id}Hapus Knowledge

Menghapus satu dokumen knowledge berdasarkan ID.

Headers
AuthorizationBearer <jwt_token>
Response
{
  "message": "Knowledge deleted"
}
DELETE/api/v1/ai/knowledge/all?device_id={device_id}Hapus Semua Knowledge

Menghapus semua dokumen knowledge untuk sebuah device. Wajib menyertakan device_id sebagai query parameter.

Headers
AuthorizationBearer <jwt_token>
Response
{
  "message": "All knowledge deleted",
  "count": 5
}
GET/api/v1/ai/creditsCek Saldo Kredit

Mendapatkan saldo kredit AI untuk perangkat yang dimiliki user. Menampilkan total kredit (paket + topup) dan detail per device.

Headers
AuthorizationBearer <jwt_token>
Response
{
  "package_credits": 1000,
  "topup_credits": 500,
  "total": 1500
}
POST/api/v1/ai/credits/topupTopup Kredit

Membuat permintaan topup kredit AI. Sistem akan membuat order dan mengirimkan permintaan pembayaran ke pixpay. Kredit akan aktif setelah pembayaran terverifikasi.

Headers
AuthorizationBearer <jwt_token>
Content-Typeapplication/json
Request Body
{
  "device_id": "uuid-device",
  "amount": 50000
}
Response
{
  "message": "Topup initiated",
  "order": {
    "id": "uuid-order",
    "amount": 50000,
    "status": "pending",
    "payment_url": "https://pixpay...",
    "qr_image": "data:image/png;base64,..."
  }
}
GET/api/v1/ai/credits/ordersRiwayat Topup

Mendapatkan riwayat permintaan topup kredit milik user. Support pagination via query page & limit.

Admin bisa melihat semua order di GET /api/v1/admin/ai/credits/device-orders.
Headers
AuthorizationBearer <jwt_token>
Response
{
  "data": [
    {
      "id": "uuid",
      "amount": 50000,
      "status": "paid",
      "created_at": "2026-06-01T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}