Developer

API Reference

Integrasi omnichannel webfy: WhatsApp Sender, WABA, Telegram, Instagram, dan Messenger — dikelompokkan per channel.

https://ruanginbox.com/api/v1Bearer authOmnichannel

Overview

API webfy untuk integrasi server-to-server. Dokumentasi dikelompokkan per channel agar endpoint WhatsApp Sender, WABA, Telegram, Instagram, dan Messenger tidak tercampur.

Auth dan error handling sama untuk semua channel. Detail send/webhook ada di masing-masing grup.

Item	Nilai
Base URL	https://ruanginbox.com/api/v1
Auth	Authorization: Bearer <api_key\|jwt>
API key	POST /api-keys` atau Dashboard → Settings → API Keys (`wgo_…`)
Login JWT	POST /auth/login

Semua path relatif ke `https://ruanginbox.com/api/v1`. Status channel: WhatsApp Sender, Telegram, Instagram, Messenger tersedia · WABA segera.

Authentication

Setiap request ke endpoint terproteksi harus mengirim header Bearer. Token bisa berupa API key (`wgo_…`) atau JWT dari login.

Header

Authorization: Bearer wgo_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
Content-Type: application/json

Error auth umum: missing/invalid Authorization — gunakan format `Bearer <token>`.

Login (JWT)

POST

https://ruanginbox.com/api/v1/auth/login

Endpoint publik (tanpa Bearer). Mengembalikan `access_token` JWT untuk memanggil API lain — termasuk membuat API key.

Field	Wajib	Keterangan
email	ya	Email user workspace
password	ya	Password akun

Request

curl -sS -X POST "https://ruanginbox.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"••••••••"}'

Response

{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": { "id": "…", "email": "you@company.com", "role": "owner" },
  "tenant": { "id": "…", "name": "Acme", "slug": "acme" }
}

Lalu pakai: `Authorization: Bearer <access_token>`. Untuk produksi, buat API key lalu simpan `raw_key`.

API keys

API key untuk server-to-server. Membuat/revoke membutuhkan JWT owner/admin. Setelah punya `raw_key`, pakai sebagai Bearer di semua channel.

POSThttps://ruanginbox.com/api/v1/api-keys

Buat API key baru. `raw_key` hanya muncul sekali di response.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/api-keys" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production bot","scopes":["*"]}'

201 Created

{
  "api_key": {
    "id": "…",
    "name": "Production bot",
    "key_prefix": "37cf346c",
    "created_at": "…"
  },
  "raw_key": "wgo_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "warning": "Store raw_key now; it will not be shown again."
}

GEThttps://ruanginbox.com/api/v1/api-keys

List API keys workspace (tanpa raw secret).

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/api-keys" \
  -H "Authorization: Bearer $API_KEY"

200

{
  "api_keys": [
    {
      "id": "…",
      "name": "Production bot",
      "key_prefix": "37cf346c",
      "revoked_at": null,
      "created_at": "…"
    }
  ]
}

DELETEhttps://ruanginbox.com/api/v1/api-keys/{api_key_id}

Revoke key aktif (status menjadi revoked).

curl

curl -sS -X DELETE "https://ruanginbox.com/api/v1/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $API_KEY"

200

{ "success": true }

DELETEhttps://ruanginbox.com/api/v1/api-keys/{api_key_id}?purge=1

Hapus permanen — hanya untuk key yang sudah revoked.

curl

curl -sS -X DELETE "https://ruanginbox.com/api/v1/api-keys/$API_KEY_ID?purge=1" \
  -H "Authorization: Bearer $API_KEY"

200

{ "success": true, "deleted": true }

Simpan `raw_key` di secret manager. Dashboard: Settings → API Keys.

Errors

HTTP	Penyebab
400	Body tidak valid
401	Token salah / hilang
404	Resource tidak ditemukan
503	Antrian / upstream tidak tersedia

json

{ "error": "to and text required" }

WhatsApp Sender

Channel WhatsApp lewat device yang terhubung (scan QR / pair). Kelola device, template, media, kirim pesan async lewat `/devices/{device_id}/messages/*`, pantau job/usage, dan webhook outbound per device.

Ini berbeda dari WABA (Meta Cloud API) — lihat grup WABA untuk jalur resmi bisnis Meta.

Capability	Status
Devices (CRUD, QR, connect)	Tersedia
Templates CRUD + render	Tersedia
Media library	Tersedia
Send text / image / template / :kind	Tersedia
Jobs & usage	Tersedia
Outbound device webhooks	Tersedia

Devices

Setiap device = satu sesi WhatsApp. Setelah create, panggil `connect` lalu ambil `qr` untuk scan, atau gunakan `pair` dengan nomor telepon.

GEThttps://ruanginbox.com/api/v1/devices

List semua device di workspace.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/devices" \
  -H "Authorization: Bearer $API_KEY"

200

{
  "devices": [
    {
      "id": "…",
      "name": "CS Line 1",
      "ruanginbox_session_id": "saas…",
      "status": "connected",
      "is_logged_in": true,
      "phone_number": "628…"
    }
  ]
}

POSThttps://ruanginbox.com/api/v1/devices

Buat device baru. Field `name` wajib.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/devices" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"CS Line 1"}'

201 Created

{
  "device": {
    "id": "…",
    "name": "CS Line 1",
    "ruanginbox_session_id": "saas…",
    "status": "created",
    "is_logged_in": false
  }
}

GEThttps://ruanginbox.com/api/v1/devices/{device_id}

Detail satu device.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/devices/$DEVICE_ID" \
  -H "Authorization: Bearer $API_KEY"

DELETEhttps://ruanginbox.com/api/v1/devices/{device_id}

Hapus device dari workspace.

curl

curl -sS -X DELETE "https://ruanginbox.com/api/v1/devices/$DEVICE_ID" \
  -H "Authorization: Bearer $API_KEY"

200

{ "success": true }

GEThttps://ruanginbox.com/api/v1/devices/{device_id}/status

Status koneksi sesi WhatsApp.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/status" \
  -H "Authorization: Bearer $API_KEY"

GEThttps://ruanginbox.com/api/v1/devices/{device_id}/qr

Ambil QR pairing. Gunakan `?ensure=1` agar sesi disiapkan jika belum ada.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/qr?ensure=1" \
  -H "Authorization: Bearer $API_KEY"

POSThttps://ruanginbox.com/api/v1/devices/{device_id}/pair

Pair via nomor telepon (pairing code), alternatif scan QR.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/pair" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"628123456789"}'

POSThttps://ruanginbox.com/api/v1/devices/{device_id}/connect

Mulai / pastikan session connect (siap QR atau pairing).

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/connect" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

POSThttps://ruanginbox.com/api/v1/devices/{device_id}/disconnect

Disconnect sesi WhatsApp device.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/disconnect" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Alur tipikal: create → connect → poll qr sampai ter-scan → `is_logged_in: true` → kirim pesan.

Templates

Message templates workspace (bukan template Meta WABA). Digunakan oleh `POST /devices/{device_id}/messages/template`. Placeholder: `{{name}}`, `{{order_id}}`, dll.

GEThttps://ruanginbox.com/api/v1/templates

List templates workspace.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/templates" \
  -H "Authorization: Bearer $API_KEY"

POSThttps://ruanginbox.com/api/v1/templates

Buat template baru.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/templates" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"order_update","kind":"text","body":"Halo {{name}}, order {{order_id}} sudah diproses."}'

GEThttps://ruanginbox.com/api/v1/templates/{template_id}

Detail template.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $API_KEY"

PUThttps://ruanginbox.com/api/v1/templates/{template_id}

Update / edit template.

curl

curl -sS -X PUT "https://ruanginbox.com/api/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"order_update","kind":"text","body":"Hi {{name}}, pesanan {{order_id}} siap dikirim.","variables":["name","order_id"]}'

DELETEhttps://ruanginbox.com/api/v1/templates/{template_id}

Hapus template.

curl

curl -sS -X DELETE "https://ruanginbox.com/api/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $API_KEY"

POSThttps://ruanginbox.com/api/v1/templates/{template_id}/render

Preview render (tanpa mengirim pesan).

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/templates/$TEMPLATE_ID/render" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"name":"Budi","order_id":"INV-1001"}}'

200

{
  "body": "Halo Budi, order INV-1001 sudah diproses."
}

Field utama: `name`, `kind` (`text`/`image`/…), `body`, `caption`, `media_id`, `variables`.

Media library

Upload file untuk dipakai di template media atau referensi internal. Max 32MB.

GEThttps://ruanginbox.com/api/v1/media

List media library.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/media" \
  -H "Authorization: Bearer $API_KEY"

POSThttps://ruanginbox.com/api/v1/media

Upload file (multipart field `file`).

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/media" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@katalog.jpg"

GEThttps://ruanginbox.com/api/v1/media/{media_id}

Metadata media asset.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/media/$MEDIA_ID" \
  -H "Authorization: Bearer $API_KEY"

GEThttps://ruanginbox.com/api/v1/media/{media_id}/file

Download file biner.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/media/$MEDIA_ID/file" \
  -H "Authorization: Bearer $API_KEY"

DELETEhttps://ruanginbox.com/api/v1/media/{media_id}

Hapus media dari library.

curl

curl -sS -X DELETE "https://ruanginbox.com/api/v1/media/$MEDIA_ID" \
  -H "Authorization: Bearer $API_KEY"

Send flow

Pastikan device sudah connected (`is_logged_in` / status connected) sebelum mengirim.

Alur

Client  →  POST /devices/{device_id}/messages/{text|image|template|:kind}
        ←  202 { job_id, status: "queued", session_id, kind }
Client  →  GET /jobs/{job_id}   (poll sampai sent|failed)
Worker  →  WhatsApp

Send text

POST

https://ruanginbox.com/api/v1/devices/{device_id}/messages/text

Kirim pesan teks. Response `202` artinya job masuk antrian — bukan pesan sudah sampai.

Field	Wajib	Keterangan
to	ya	Nomor internasional tanpa `+` / spasi, atau JID WhatsApp
text	ya	Isi pesan

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/messages/text" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"628123456789","text":"Halo dari webfy API"}'

202 Accepted

{
  "job_id": "7c2e9f0a-….uuid",
  "status": "queued",
  "session_id": "ruanginbox-session-id",
  "kind": "text"
}

Send image

POST

https://ruanginbox.com/api/v1/devices/{device_id}/messages/image

Sediakan salah satu: `image.url` (publik) atau `image.data` (base64).

Field	Wajib	Keterangan
to	ya	Penerima
image.url atau image.data	ya	URL publik atau base64
image.mimetype	disarankan	image/jpeg`, `image/png`, …
caption	tidak	Teks di bawah gambar

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/messages/image" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"628123456789","caption":"Katalog Juli","image":{"url":"https://cdn.example.com/katalog.jpg","mimetype":"image/jpeg"}}'

Body (JSON)

{
  "to": "628123456789",
  "caption": "Katalog Juli",
  "image": {
    "url": "https://cdn.example.com/katalog.jpg",
    "mimetype": "image/jpeg"
  }
}

Send template

POST

https://ruanginbox.com/api/v1/devices/{device_id}/messages/template

Memakai Message Template di dashboard (`/templates`). Placeholder seperti `{{name}}` diganti saat kirim.

Field	Wajib	Keterangan
template_id	ya	UUID template workspace
to	ya*	Wajib kecuali contact punya nomor
variables	tidak	Map placeholder → nilai
contact_id	tidak	Auto-isi name/phone/email (+ to bila kosong)

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/messages/template" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"628123456789","template_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee","variables":{"name":"Budi","order_id":"INV-1001"}}'

Body (JSON)

{
  "to": "628123456789",
  "template_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "variables": {
    "name": "Budi",
    "order_id": "INV-1001"
  }
}

Send by kind

POST

https://ruanginbox.com/api/v1/devices/{device_id}/messages/{kind}

Endpoint generik untuk jenis pesan selain shortcut text/image/template. Body mengikuti skema Waxum untuk `kind` tersebut; response tetap `202` + `job_id`.

kind (contoh)	Keterangan
audio / video / document / sticker	Media
location / contact	Lokasi / vCard
react / read / revoke / edit / forward	Aksi pesan
poll / buttons / list / interactive	Interaktif
cta-url / quick-reply	CTA

curl — document

curl -sS -X POST "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/messages/document" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"628123456789","document":{"url":"https://cdn.example.com/invoice.pdf","mimetype":"application/pdf"},"filename":"invoice.pdf"}'

Job status

GET

https://ruanginbox.com/api/v1/jobs/{job_id}

Poll tiap 1–2 detik sampai `sent` atau `failed`. Job hanya terlihat oleh tenant pemilik device.

status	Arti
queued	Menunggu worker
processing	Sedang dikirim
sent	Berhasil
failed	Gagal — lihat field `error

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $API_KEY"

200

{
  "id": "…",
  "session_id": "ruanginbox-session-id",
  "kind": "text",
  "status": "sent",
  "message_id": "…",
  "error": null
}

Usage & jobs list

Ringkasan traffic device dan daftar send jobs.

GEThttps://ruanginbox.com/api/v1/devices/{device_id}/usage?days=30

Counter inbound / outbound / jobs untuk device.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/usage?days=30" \
  -H "Authorization: Bearer $API_KEY"

200

{
  "device_id": "…",
  "session_id": "ruanginbox-session-id",
  "inbound": 120,
  "outbound": 95,
  "jobs_queued": 0,
  "jobs_sent": 90,
  "jobs_failed": 5,
  "jobs_total": 95,
  "is_logged_in": true,
  "device_status": "connected"
}

GEThttps://ruanginbox.com/api/v1/devices/{device_id}/jobs?limit=40&status=sent

List jobs pengiriman per device (filter `status` opsional).

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/jobs?limit=40&status=sent" \
  -H "Authorization: Bearer $API_KEY"

Device webhooks

Atur URL outbound per device. webfy menerima event WhatsApp secara internal, lalu meneruskan ke URL Anda bila webhook diaktifkan.

UI: Devices → pilih device → tab Webhook.

GEThttps://ruanginbox.com/api/v1/devices/{device_id}/webhook-settings

Ambil pengaturan webhook device.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/webhook-settings" \
  -H "Authorization: Bearer $API_KEY"

PUThttps://ruanginbox.com/api/v1/devices/{device_id}/webhook-settings

Simpan URL, secret, events, dan status enabled.

curl

curl -sS -X PUT "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/webhook-settings" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/hooks/whatsapp","secret":"optional-hmac-secret","enabled":true,"events":["whatsapp.message.inbound","whatsapp.message.sent","whatsapp.message.failed"]}'

Payload ke URL Anda

{
  "id": "delivery-uuid",
  "event": "whatsapp.message.inbound",
  "device_id": "…",
  "tenant_id": "…",
  "session_id": "ruanginbox-session-id",
  "timestamp": "2026-08-04T12:00:00Z",
  "data": { "from": "628…", "text": "Halo", "conversation_id": "…" }
}

POSThttps://ruanginbox.com/api/v1/devices/{device_id}/webhook-settings/test

Kirim event uji ke URL webhook.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/webhook-settings/test" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GEThttps://ruanginbox.com/api/v1/devices/{device_id}/webhook-deliveries

Riwayat delivery webhook (sukses/gagal).

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/devices/$DEVICE_ID/webhook-deliveries" \
  -H "Authorization: Bearer $API_KEY"

Signature: `X-Webhook-Signature: sha256=<hmac-sha256(secret, raw_body)>`. `events: []` = semua event.

Code examples

Contoh minimal Node.js untuk kirim teks lewat WhatsApp Sender.

javascript

const API = process.env.RUANGINBOX_API || "https://ruanginbox.com/api/v1";
const KEY = process.env.RUANGINBOX_API_KEY;
const DEVICE = process.env.DEVICE_ID;

async function sendText(to, text) {
  const res = await fetch(`${API}/devices/${DEVICE}/messages/text`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ to, text }),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json(); // { job_id, status, session_id, kind }
}

Jangan asumsikan `202` = pesan sudah sampai. Pantau job status atau webhook `whatsapp.message.sent` / `failed`.

WABA (WhatsApp Cloud API)

Jalur WhatsApp Business API resmi Meta (Cloud API / phone number ID). Mendukung mode Official API dan Coexistence.

Kelola akun di Settings → Channels → WhatsApp Official API / WhatsApp Coexistence. Webhook inbound memakai `POST /api/v1/webhooks/meta` (object `whatsapp_business_account`).

GEThttps://ruanginbox.com/api/v1/channels/whatsapp-cloud/accounts?mode=official|coexistence

List akun Cloud API workspace.

POSThttps://ruanginbox.com/api/v1/channels/whatsapp-cloud/accounts

Tambah akun (phone_number_id + access_token + connection_mode).

POSThttps://ruanginbox.com/api/v1/channels/whatsapp-cloud/accounts/{account_id}/connect

Validasi token ke Graph API dan set status connected.

POSThttps://ruanginbox.com/api/v1/channels/whatsapp-cloud/accounts/{account_id}/messages/text

Kirim teks via Cloud API.

Capability	Status
Connect WABA / phone number	Tersedia
Send text via Cloud API	Tersedia
Inbound webhook → Unified Inbox	Tersedia
Official vs Coexistence modes	Tersedia
Meta template sync	Segera

WhatsApp Sender (device/QR) tetap terpisah di Devices. Coexistence membutuhkan onboarding Meta Coexistence sebelum token Cloud API aktif.

Kelola akun Telegram (Bot API atau client MTProto per tenant), terima pesan ke Unified Inbox, balas dari inbox, kirim lewat public send API, dan fan-out event ke URL Anda.

Client login memakai `api_id` + `api_hash` per akun (dari my.telegram.org/apps) — bukan env server global.

Berbeda dari WhatsApp Sender: pengiriman Telegram sinkron (langsung `sent`), bukan job antrian `202`.

Panduan onboarding step-by-step ada di section Setup (Bot API dan Client login).

Capability	Status
Bot CRUD + connect webhook	Tersedia
Client login (MTProto) + OTP/2FA	Tersedia
Inbound teks + media → inbox	Tersedia
Inbox agent reply	Tersedia
Send text / photo / document	Tersedia
Outbound developer webhooks	Tersedia
Assign AI employee	Tersedia

Setup Telegram

Onboarding step-by-step per workspace (multi-tenant SaaS).

Pilih satu mode per akun: Bot API (BotFather) atau Client login (nomor HP + app Telegram milik tenant). Keduanya masuk Unified Inbox yang sama.

Untuk Client login, `api_id` dan `api_hash` diisi per akun (dari my.telegram.org/apps) — setiap tenant membawa kredensial app mereka sendiri, bukan env server.

UI: Settings → Channels → Telegram. Atau ikuti langkah API di bawah.

Langkah	Bot API	Client login (MTProto)
1. Siapkan kredensial	Buka @BotFather → /newbot → salin bot token	Buka my.telegram.org/apps → buat app → salin API ID + API Hash; siapkan nomor internasional (+62…)
2. Buat akun	POST /channels/telegram/bots dengan auth_mode=bot + bot_token	POST /channels/telegram/bots dengan auth_mode=client + phone + api_id + api_hash
3. Autentikasi	Tidak perlu OTP (token sudah cukup)	send-code → confirm-code → (opsional) confirm-2fa jika cloud password aktif
4. Connect	POST .../connect mendaftarkan webhook inbound ke Telegram	POST .../connect menjalankan sesi MTProto setelah login sukses
5. Uji	User kirim /start ke bot → cek Unified Inbox → balas / assign AI	User chat ke nomor yang login → cek Unified Inbox → balas / assign AI

Bot API — create + connect

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_mode":"bot","name":"Support Bot","bot_token":"123456:ABC-DEF…"}'



curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/connect" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Client login — create → OTP → connect

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_mode":"client","name":"CS Personal","phone":"+62812…","api_id":12345678,"api_hash":"hex_dari_my_telegram_org"}'



curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/send-code" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'



curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/confirm-code" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"12345"}'



# jika response step = awaiting_2fa:

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/confirm-2fa" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password":"cloud_password"}'



curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/connect" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Mode Bot: user harus /start bot sebelum bot bisa DM. Mode Client memakai sesi user Telegram (bukan bot) — patuhi ToS Telegram dan kebijakan tenant Anda. Setelah connect, lanjut assign AI atau set outbound webhook bila perlu.

Bots / accounts

Kelola akun Telegram workspace. `auth_mode=bot` (default) butuh `bot_token`. `auth_mode=client` butuh `phone`, `api_id`, dan `api_hash` milik tenant.

Setelah create client, lanjutkan alur send-code → confirm-code (→ confirm-2fa) → connect. Lihat Setup.

GEThttps://ruanginbox.com/api/v1/channels/telegram/bots

List bots / client accounts workspace.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/telegram/bots" \
  -H "Authorization: Bearer $API_KEY"

POSThttps://ruanginbox.com/api/v1/channels/telegram/bots

Create bot atau client account.

Bot: `{ auth_mode?: "bot", name, bot_token }`. Client: `{ auth_mode: "client", name, phone, api_id, api_hash }`.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_mode":"client","name":"CS Personal","phone":"+62812…","api_id":12345678,"api_hash":"…"}'

GEThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}

Detail bot.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID" \
  -H "Authorization: Bearer $API_KEY"

DELETEhttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}

Hapus bot dari workspace.

curl

curl -sS -X DELETE "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID" \
  -H "Authorization: Bearer $API_KEY"

POSThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/send-code

Client only — kirim OTP ke nomor / Telegram app.

Opsional body `{ phone }` untuk override nomor yang tersimpan.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/send-code" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

POSThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/confirm-code

Client only — konfirmasi OTP. Body: `{ code }`.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/confirm-code" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"12345"}'

POSThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/confirm-2fa

Client only — cloud password bila 2FA aktif. Body: `{ password }`.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/confirm-2fa" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password":"…"}'

POSThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/connect

Bot: setWebhook. Client: start sesi MTProto (login harus selesai).

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/connect" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

POSThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/assign-ai

Assign AI employee ke bot.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/assign-ai" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"…","enabled":true}'

GEThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/assigned-ai

Lihat assignment AI aktif.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/assigned-ai" \
  -H "Authorization: Bearer $API_KEY"

Send text

POST

https://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/messages/text

Kirim teks sinkron lewat Bot API. `chat_id` adalah ID chat Telegram (string atau number). Conversation inbox di-upsert otomatis.

Field	Wajib	Keterangan
chat_id	ya	Telegram chat id
text	ya	Isi pesan

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/messages/text" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"123456789","text":"Halo dari webfy API"}'

Response

{
  "ok": true,
  "bot_id": "…",
  "chat_id": "123456789",
  "conversation_id": "…",
  "message_id": "…",
  "telegram_message_id": 42,
  "status": "sent",
  "kind": "text"
}

User harus pernah start bot (`/start`) atau chat terbuka; jika belum, Telegram mengembalikan error (HTTP 502).

Send photo

POST

https://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/messages/photo

Kirim foto sinkron. Sediakan `photo.url` (HTTPS publik) atau `photo.data` (base64).

Field	Wajib	Keterangan
chat_id	ya	Telegram chat id
photo.url atau photo.data	ya	URL publik atau base64
caption	tidak	Caption di bawah foto

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/messages/photo" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"123456789","caption":"Katalog Juli","photo":{"url":"https://cdn.example.com/katalog.jpg"}}'

Send document

POST

https://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/messages/document

Kirim dokumen (PDF, dll). Sediakan `document.url` atau `document.data`.

Field	Wajib	Keterangan
chat_id	ya	Telegram chat id
document.url atau document.data	ya	URL atau base64
caption	tidak	Caption
filename	disarankan	Nama file yang tampil

json

{
  "chat_id": "123456789",
  "filename": "invoice.pdf",
  "document": {
    "url": "https://cdn.example.com/invoice.pdf"
  }
}

Inbound webhook

POST

https://ruanginbox.com/api/v1/webhooks/telegram/{secret}

Endpoint publik yang dipanggil Telegram setelah `connect` (mode Bot API). Secret ada di konfigurasi bot.

Pesan teks/caption dan media (photo, document, video, audio, voice, sticker) masuk Unified Inbox. Media disimpan ke Media library.

Mode Client tidak memakai URL webhook ini — inbound datang lewat sesi MTProto setelah `connect`.

Opsional header `X-Telegram-Bot-Api-Secret-Token`. Ini inbound Telegram→webfy — beda dari outbound webhook di bawah.

Outbound webhooks

Atur URL outbound per bot. webfy meneruskan event ke URL Anda bila diaktifkan (pola sama seperti WhatsApp device webhooks).

GEThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/webhook-settings

Ambil pengaturan webhook bot.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/webhook-settings" \
  -H "Authorization: Bearer $API_KEY"

PUThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/webhook-settings

Simpan URL, secret, events.

curl

curl -sS -X PUT "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/webhook-settings" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/hooks/telegram","secret":"optional-hmac-secret","enabled":true,"events":["telegram.message.inbound","telegram.message.sent"]}'

POSThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/webhook-settings/test

Kirim event uji.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/webhook-settings/test" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GEThttps://ruanginbox.com/api/v1/channels/telegram/bots/{bot_id}/webhook-deliveries

Riwayat delivery.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/telegram/bots/$BOT_ID/webhook-deliveries" \
  -H "Authorization: Bearer $API_KEY"

Signature: `X-Webhook-Signature: sha256=<hmac>`. Header ekstra: `X-RuangInbox-Event`, `X-RuangInbox-Bot-Id`. `events: []` = semua event.

Instagram

Instagram Messaging lewat Facebook Page yang terhubung ke Instagram Business Account. Page dikelola di `/channels/meta/pages`; send/inbox memakai channel `instagram`.

Setup Meta App: Webhooks callback = `https://ruanginbox.com/api/v1/webhooks/meta` + `META_WEBHOOK_VERIFY_TOKEN` / `META_APP_SECRET` di server.

Capability	Status
Meta page CRUD + connect	Tersedia
Inbound DM → Unified Inbox	Tersedia
Inbox agent reply	Tersedia
Send text / image	Tersedia
Outbound developer webhooks	Tersedia

Meta pages (shared)

Instagram dan Messenger memakai resource yang sama: Facebook Page + Page Access Token. Buat page sekali, aktifkan Instagram bila ada `ig_user_id`.

GEThttps://ruanginbox.com/api/v1/channels/meta/pages

List Meta pages workspace.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/meta/pages" \
  -H "Authorization: Bearer $API_KEY"

POSThttps://ruanginbox.com/api/v1/channels/meta/pages

Create page — `page_id` + `page_access_token` wajib; `ig_user_id` opsional.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/meta/pages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support","page_id":"1234567890","page_access_token":"EAAB…","ig_user_id":"1784…"}'

GEThttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}

Detail page (UUID webfy).

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID" \
  -H "Authorization: Bearer $API_KEY"

DELETEhttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}

Hapus page dari workspace.

curl

curl -sS -X DELETE "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID" \
  -H "Authorization: Bearer $API_KEY"

POSThttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}/connect

Validasi token, discover IG, subscribe apps.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID/connect" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Send text

POST

https://ruanginbox.com/api/v1/channels/instagram/pages/{page_id}/messages/text

`page_id` = UUID webfy (bukan Facebook Page ID). `recipient_id` = Instagram Scoped ID (IGSID).

Field	Wajib	Keterangan
recipient_id	ya	IGSID (alias: `igsid`)
text	ya	Isi pesan

bash

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/instagram/pages/$PAGE_UUID/messages/text" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient_id":"IGSID…","text":"Halo dari webfy"}'

Send image

POST

https://ruanginbox.com/api/v1/channels/instagram/pages/{page_id}/messages/image

Kirim gambar via URL publik HTTPS.

json

{
  "recipient_id": "IGSID…",
  "image": { "url": "https://cdn.example.com/katalog.jpg" }
}

Inbound webhook

POST

https://ruanginbox.com/api/v1/webhooks/meta

Satu endpoint Meta untuk Instagram + Messenger. GET untuk hub.verify_token; POST untuk events.

Pesan Instagram masuk inbox dengan `channel_type=instagram`.

Signature: `X-Hub-Signature-256` dengan `META_APP_SECRET`. Verify: `META_WEBHOOK_VERIFY_TOKEN`.

Outbound webhooks

Outbound per Meta page (sama resource dengan Messenger). Event Instagram: `instagram.message.*`.

GEThttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}/webhook-settings

Ambil pengaturan webhook page.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID/webhook-settings" \
  -H "Authorization: Bearer $API_KEY"

PUThttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}/webhook-settings

Simpan URL outbound + events.

curl

curl -sS -X PUT "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID/webhook-settings" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/hooks/meta","secret":"optional-hmac-secret","enabled":true,"events":["instagram.message.inbound","instagram.message.sent"]}'

POSThttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}/webhook-settings/test

Kirim event uji.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID/webhook-settings/test" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GEThttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}/webhook-deliveries

Riwayat delivery.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID/webhook-deliveries" \
  -H "Authorization: Bearer $API_KEY"

Messenger

Facebook Messenger lewat Facebook Page yang sama dengan Instagram. Send API di `/channels/messenger/…`; inbox `channel_type=messenger`.

Capability	Status
Meta page CRUD + connect	Tersedia
Inbound DM → Unified Inbox	Tersedia
Inbox agent reply	Tersedia
Send text / image	Tersedia
Outbound developer webhooks	Tersedia

Meta pages (shared)

Lihat juga section Instagram → Meta pages. Resource `/channels/meta/pages` dipakai bersama.

GEThttps://ruanginbox.com/api/v1/channels/meta/pages

List pages (sama endpoint Instagram).

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/meta/pages" \
  -H "Authorization: Bearer $API_KEY"

POSThttps://ruanginbox.com/api/v1/channels/meta/pages

Create page + Page Access Token.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/meta/pages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support","page_id":"1234567890","page_access_token":"EAAB…"}'

POSThttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}/connect

Subscribe messaging fields Meta.

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID/connect" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Send text

POST

https://ruanginbox.com/api/v1/channels/messenger/pages/{page_id}/messages/text

`recipient_id` = Page-Scoped ID (PSID).

Field	Wajib	Keterangan
recipient_id	ya	PSID (alias: `psid`)
text	ya	Isi pesan

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/messenger/pages/$PAGE_UUID/messages/text" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient_id":"PSID…","text":"Halo dari webfy"}'

Send image

POST

https://ruanginbox.com/api/v1/channels/messenger/pages/{page_id}/messages/image

curl

curl -sS -X POST "https://ruanginbox.com/api/v1/channels/messenger/pages/$PAGE_UUID/messages/image" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient_id":"PSID…","image_url":"https://cdn.example.com/banner.jpg"}'

Inbound webhook

POST

https://ruanginbox.com/api/v1/webhooks/meta

Sama dengan Instagram: `GET/POST /webhooks/meta`. Event Messenger masuk inbox `channel_type=messenger`.

Subscribe field `messages` pada Page di Meta App Dashboard.

Outbound webhooks

Event Messenger: `messenger.message.inbound|sent|failed`. Settings di `/channels/meta/pages/{page_id}/webhook-settings` (sama resource Instagram).

GEThttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}/webhook-settings

Ambil pengaturan webhook page.

curl

curl -sS -X GET "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID/webhook-settings" \
  -H "Authorization: Bearer $API_KEY"

PUThttps://ruanginbox.com/api/v1/channels/meta/pages/{page_id}/webhook-settings

Simpan URL + events Messenger.

curl

curl -sS -X PUT "https://ruanginbox.com/api/v1/channels/meta/pages/$PAGE_UUID/webhook-settings" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/hooks/meta","enabled":true,"events":["messenger.message.inbound","messenger.message.sent","meta.page.connected"]}'