Getting Started

Waslah REST API memungkinkan integrasi WhatsApp dengan sistem apa pun — e-commerce, CRM, ERP, atau script internal. Cocok untuk notifikasi transaksional, OTP, reminder, dan auto reply.

Authentication

Semua endpoint (kecuali webhook receiver) butuh API key. Kirim via header Authorization Bearer atau X-API-Key:

curl -H "Authorization: Bearer wsl_YOUR_TOKEN_HERE" \
     https://waslah.id/api/v1/me

fetch('https://waslah.id/api/v1/me', {
  headers: { 'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE' }
})
  .then(r => r.json())
  .then(console.log);

<?php
$ch = curl_init('https://waslah.id/api/v1/me');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer wsl_YOUR_TOKEN_HERE',
    'Accept: application/json',
]);
$response = curl_exec($ch);
echo $response;

import requests

r = requests.get(
    'https://waslah.id/api/v1/me',
    headers={'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE'}
)
print(r.json())

Base URL

Semua endpoint dimulai dengan base URL berikut:

https://waslah.id/api/v1

Dapatkan info user pemilik API key + metadata key (request count, last used, scopes). Tidak butuh scope khusus.

Response 200

{
  "ok": true,
  "data": {
    "user": {
      "id": 1,
      "name": "Admin",
      "email": "admin@waslah.id"
    },
    "api_key": {
      "id": 2,
      "name": "Production Server",
      "prefix": "wsl_a3f29d4b",
      "scopes": ["messages:send", "messages:read", "instances:read"],
      "request_count": 42,
      "last_used_at": "2026-05-11T17:24:02+00:00",
      "expires_at": null
    }
  }
}

curl -H "Authorization: Bearer wsl_YOUR_TOKEN_HERE" \
     https://waslah.id/api/v1/me

const res = await fetch('https://waslah.id/api/v1/me', {
  headers: { 'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE' }
});
const { data } = await res.json();
console.log(data.user.email);

$client = new \GuzzleHttp\Client();
$res = $client->get('https://waslah.id/api/v1/me', [
    'headers' => ['Authorization' => 'Bearer wsl_YOUR_TOKEN_HERE'],
]);
$data = json_decode($res->getBody(), true);

import requests

r = requests.get(
    'https://waslah.id/api/v1/me',
    headers={'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE'}
)
data = r.json()['data']
print(data['user']['email'])

List semua instance WhatsApp milik user.

Response 200

{
  "ok": true,
  "data": [
    {
      "id": 1,
      "key": "fathur-utama",
      "name": "fathur romadhon",
      "status": "connected",
      "phone_number": "6285815004099",
      "connected_at": "2026-05-11T16:32:49+00:00",
      "last_seen_at": "2026-05-11T17:30:00+00:00",
      "created_at": "2026-05-10T...",
      "disconnected_at": null
    }
  ]
}

curl -H "Authorization: Bearer wsl_YOUR_TOKEN_HERE" \
     https://waslah.id/api/v1/instances

const res = await fetch('https://waslah.id/api/v1/instances', {
  headers: { 'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE' }
});
const { data } = await res.json();
data.forEach(i => console.log(i.key, i.status));

$res = (new \GuzzleHttp\Client())->get('https://waslah.id/api/v1/instances', [
    'headers' => ['Authorization' => 'Bearer wsl_YOUR_TOKEN_HERE'],
]);
$instances = json_decode($res->getBody(), true)['data'];

r = requests.get(
    'https://waslah.id/api/v1/instances',
    headers={'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE'}
)
for inst in r.json()['data']:
    print(inst['key'], inst['status'])

Detail satu instance berdasarkan key.

Path Parameter

curl -H "Authorization: Bearer wsl_YOUR_TOKEN_HERE" \
     https://waslah.id/api/v1/instances/fathur-utama

const res = await fetch('https://waslah.id/api/v1/instances/fathur-utama', {
  headers: { 'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE' }
});

$res = (new \GuzzleHttp\Client())->get('https://waslah.id/api/v1/instances/fathur-utama', [
    'headers' => ['Authorization' => 'Bearer wsl_YOUR_TOKEN_HERE'],
]);

r = requests.get(
    'https://waslah.id/api/v1/instances/fathur-utama',
    headers={'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE'}
)

Upload file (multipart/form-data). Return public URL yang bisa langsung dipakai untuk /messages/media atau /messages/bulk. Max 16MB. Tidak konsumsi quota.

Allowed MIME types

Image: jpeg, png, webp, gif  ·  Video: mp4, quicktime  ·  Audio: mpeg, mp4, ogg, wav, aac  ·  Document: pdf, doc/docx, xls/xlsx, ppt/pptx, txt, csv, zip

Response 200

{
  "ok": true,
  "data": {
    "url": "https://waslah.id/storage/uploads/2026-05/9c5b...-uuid.jpg",
    "path": "uploads/2026-05/9c5b...-uuid.jpg",
    "filename": "kucing.jpg",
    "size": 245870,
    "mime_type": "image/jpeg",
    "type": "image"
  }
}

url = public URL siap pakai (paste ke /messages/media.url). path = relative storage path (untuk delete/admin use). type = auto-detect dari MIME (image|video|audio|document).

Response 422 (MIME tidak didukung)

{
  "ok": false,
  "error": "unsupported_media_type",
  "message": "MIME type `application/x-foo` tidak didukung. Cek dokumentasi untuk format yang diterima.",
  "mime_type": "application/x-foo"
}

Response 422 (Validation gagal, mis. file kosong / >16MB)

{
  "ok": false,
  "error": "validation_failed",
  "message": "File tidak valid: The file field is required.",
  "errors": {
    "file": ["The file field is required."]
  }
}

curl -X POST https://waslah.id/api/v1/uploads \
  -H "Authorization: Bearer wsl_YOUR_TOKEN_HERE" \
  -F "file=@/path/to/image.jpg"

const fd = new FormData();
fd.append('file', fileInput.files[0]);

const res = await fetch('https://waslah.id/api/v1/uploads', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE' },
  body: fd,
});
const { data } = await res.json();
console.log('Uploaded URL:', data.url);

$client = new \GuzzleHttp\Client();
$res = $client->post('https://waslah.id/api/v1/uploads', [
    'headers' => ['Authorization' => 'Bearer wsl_YOUR_TOKEN_HERE'],
    'multipart' => [
        ['name' => 'file', 'contents' => fopen('/path/to/image.jpg', 'r')],
    ],
]);
$url = json_decode($res->getBody(), true)['data']['url'];

with open('/path/to/image.jpg', 'rb') as f:
    r = requests.post(
        'https://waslah.id/api/v1/uploads',
        headers={'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE'},
        files={'file': f},
    )
url = r.json()['data']['url']

Cek status pesan. Status bisa pending, sent, delivered, read, failed.

Response 200

{
  "ok": true,
  "data": {
    "id": 5,
    "instance_key": "fathur-utama",
    "direction": "outbound",
    "status": "sent",
    "message_type": "text",
    "phone_number": "6285815004099",
    "remote_jid": "6285815004099@s.whatsapp.net",
    "body": "Halo dari API",
    "media_url": null,
    "media_filename": null,
    "media_mime_type": null,
    "provider_message_id": "BAE5...",
    "error_message": null,
    "sent_at": "2026-05-19T...",
    "received_at": null,
    "scheduled_at": null,
    "created_at": "2026-05-19T...",
    "updated_at": "2026-05-19T..."
  }
}

Untuk pesan media: message_type = image|video|audio|document|sticker, media_url berisi URL file. Untuk reply ke conversation LID (privacy mode), remote_jid akan berakhiran @lid alih-alih @s.whatsapp.net — pakai value remote_jid persis di field to saat call /messages/text / /messages/media untuk reply ke customer LID.

Response 404

{
  "ok": false,
  "error": "not_found",
  "message": "Message dengan ID `99999` tidak ditemukan atau bukan milik Anda."
}

curl -H "Authorization: Bearer wsl_YOUR_TOKEN_HERE" \
     https://waslah.id/api/v1/messages/5

// Poll status sampai final (sent/delivered/failed)
async function pollStatus(id, token) {
  while (true) {
    const r = await fetch(`https://waslah.id/api/v1/messages/${id}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const { data } = await r.json();
    if (data.status !== 'pending') return data;
    await new Promise(r => setTimeout(r, 2000));
  }
}

function pollStatus(int $id, string $token): array {
    $client = new \GuzzleHttp\Client();
    while (true) {
        $res = $client->get("https://waslah.id/api/v1/messages/$id", [
            'headers' => ['Authorization' => "Bearer $token"]
        ]);
        $data = json_decode($res->getBody(), true)['data'];
        if ($data['status'] !== 'pending') return $data;
        sleep(2);
    }
}

import requests, time

def poll_status(id, token):
    while True:
        r = requests.get(
            f'https://waslah.id/api/v1/messages/{id}',
            headers={'Authorization': f'Bearer {token}'}
        )
        data = r.json()['data']
        if data['status'] != 'pending':
            return data
        time.sleep(2)

List 50 broadcast terakhir milik user dengan progress real-time.

curl -H "Authorization: Bearer wsl_YOUR_TOKEN_HERE" \
     https://waslah.id/api/v1/broadcasts

const res = await fetch('https://waslah.id/api/v1/broadcasts', {
  headers: { 'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE' }
});
const { data } = await res.json();
data.forEach(b => console.log(b.id, b.status, `${b.sent}/${b.total}`));

$res = (new \GuzzleHttp\Client())->get('https://waslah.id/api/v1/broadcasts', [
    'headers' => ['Authorization' => 'Bearer wsl_YOUR_TOKEN_HERE'],
]);

r = requests.get('https://waslah.id/api/v1/broadcasts',
    headers={'Authorization': 'Bearer wsl_YOUR_TOKEN_HERE'}
)
for b in r.json()['data']:
    print(b['id'], b['status'], f"{b['sent']}/{b['total']}")

Cek progress real-time broadcast. Poll endpoint ini sampai status jadi completed atau failed.

Response 200

{
  "ok": true,
  "data": {
    "id": 3,
    "name": "Promo Akhir Bulan",
    "message_type": "text",
    "instance_key": "fathur-utama",
    "status": "processing",
    "total": 50,
    "sent": 32,
    "failed": 1,
    "pending": 17,
    "progress_percent": 66,
    "delay_min_sec": 3,
    "delay_max_sec": 8,
    "delay_label": "3–8 detik",
    "created_at": "2026-05-19T...",
    "completed_at": null
  }
}

status ∈ queued|processing|completed|failed. delay_label human-readable (mis. 3 detik (fixed) kalau min=max). completed_at diisi saat status final.

curl -H "Authorization: Bearer wsl_YOUR_TOKEN_HERE" \
     https://waslah.id/api/v1/broadcasts/3

// Poll progress sampai selesai
async function trackBroadcast(id, token) {
  while (true) {
    const r = await fetch(`https://waslah.id/api/v1/broadcasts/${id}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const { data } = await r.json();
    console.log(`${data.progress_percent}% — sent ${data.sent}/${data.total}`);
    if (data.status !== 'processing') return data;
    await new Promise(r => setTimeout(r, 3000));
  }
}

function trackBroadcast(int $id, string $token): array {
    $client = new \GuzzleHttp\Client();
    while (true) {
        $res = $client->get("https://waslah.id/api/v1/broadcasts/$id", [
            'headers' => ['Authorization' => "Bearer $token"]
        ]);
        $data = json_decode($res->getBody(), true)['data'];
        echo $data['progress_percent'] . "% — sent {$data['sent']}/{$data['total']}\n";
        if ($data['status'] !== 'processing') return $data;
        sleep(3);
    }
}

import time

def track_broadcast(id, token):
    while True:
        r = requests.get(f'https://waslah.id/api/v1/broadcasts/{id}',
            headers={'Authorization': f'Bearer {token}'}
        )
        d = r.json()['data']
        print(f"{d['progress_percent']}% — sent {d['sent']}/{d['total']}")
        if d['status'] != 'processing':
            return d
        time.sleep(3)

Error Codes

Semua error response punya format konsisten:

{
  "ok": false,
  "error": "error_code_string",
  "message": "Human-readable message",
  ...additional context...
}

Rate Limits per Plan

Limit di-scope per API key, di-track per menit. Kalau exceed, response 429 Too Many Requests.

Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1699999999
Retry-After: 12

Scopes

Scope membatasi apa yang bisa dilakukan API key. Set seminimal mungkin (principle of least privilege).

Outbound Webhooks

Daftarkan URL endpoint kamu — Waslah akan POST event real-time saat ada pesan masuk, status update, dst. Butuh plan Basic+.

Setup

1. Buka Developer → Webhooks → klik Tambah Webhook
2. Isi URL endpoint (HTTPS recommended), pilih event yang di-subscribe
3. Catat secret yang ter-generate — dipakai untuk verify signature

Event types

Headers yang Waslah kirim

Setiap webhook POST mengirim headers berikut. Signature dikirim di 5 alias header sekaligus untuk maximum compatibility dengan berbagai framework — pilih salah satu di kode validator kamu.

Formula HMAC SHA-256

payload_to_sign = X-Waslah-Timestamp + "." + raw_request_body
signature       = HMAC-SHA256(payload_to_sign, webhook_secret)
header_value    = "sha256=" + bin2hex(signature)

Contoh Validator — PHP (vanilla)

$timestamp = $_SERVER['HTTP_X_WASLAH_TIMESTAMP'] ?? '';
$header = $_SERVER['HTTP_X_WASLAH_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
$secret = 'YOUR_WEBHOOK_SECRET'; // dari dashboard

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (! hash_equals($expected, $header)) {
    http_response_code(401);
    exit(json_encode(['ok' => false, 'error' => 'Invalid signature']));
}

// Anti-replay: reject kalau timestamp > 5 menit lalu
if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit(json_encode(['ok' => false, 'error' => 'Timestamp too old']));
}

$data = json_decode($body, true);
// ... process event ...
http_response_code(200);
echo json_encode(['ok' => true]);

Contoh Validator — Node.js / Express

const crypto = require('crypto');
const express = require('express');
const app = express();

// PENTING: raw body required untuk signature verify
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const timestamp = req.header('X-Waslah-Timestamp');
    const received = req.header('X-Waslah-Signature');
    const body = req.body.toString('utf8');
    const secret = process.env.WASLAH_WEBHOOK_SECRET;

    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(timestamp + '.' + body)
        .digest('hex');

    if (! crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
        return res.status(401).json({ ok: false, error: 'Invalid signature' });
    }

    if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
        return res.status(401).json({ ok: false, error: 'Timestamp too old' });
    }

    const data = JSON.parse(body);
    console.log('Event:', data.event, data.data);
    res.json({ ok: true });
});

Contoh Validator — Python / Flask

import hmac, hashlib, time
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET = b'YOUR_WEBHOOK_SECRET'

@app.route('/webhook', methods=['POST'])
def webhook():
    timestamp = request.headers.get('X-Waslah-Timestamp', '')
    received = request.headers.get('X-Waslah-Signature', '')
    body = request.get_data()

    expected = 'sha256=' + hmac.new(
        SECRET, (timestamp + '.').encode() + body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, received):
        return jsonify(ok=False, error='Invalid signature'), 401

    if abs(time.time() - int(timestamp)) > 300:
        return jsonify(ok=False, error='Timestamp too old'), 401

    data = request.get_json()
    print('Event:', data['event'], data['data'])
    return jsonify(ok=True)

Example payload (message.received)

{
  "event": "message.received",
  "timestamp": 1715000000,
  "data": {
    "message_id": 1234,
    "instance_key": "fathur-utama",
    "from": "6281234567890",
    "remote_jid": "6281234567890@s.whatsapp.net",
    "body": "Halo, info produk",
    "message_type": "text",
    "received_at": "2026-05-12T11:05:23+07:00"
  }
}

// Contoh auto-reply Node.js
app.post('/webhook', (req, res) => {
  const { event, data } = req.body;
  if (event === 'message.received') {
    fetch('https://waslah.id/api/v1/messages/text', {
      method: 'POST',
      headers: { 'Authorization': 'Bearer wsl_xxx', 'Content-Type': 'application/json' },
      body: JSON.stringify({
        instance_key: data.instance_key,
        to: data.remote_jid, // ← pakai JID utuh, bukan data.from
        text: 'Terima kasih, pesan kamu sudah kami terima.'
      })
    });
  }
  res.json({ ok: true });
});