Panduan Channel API

1. Persiapan di Rspond

1. Pastikan channel API ada di paket workspace (Billing → pilih API sebagai channel paket atau channel tambahan).
2. Buka Channel → API → Buat koneksi API. Isi URL webhook balasan bila server Anda bisa menerima POST dari internet (HTTPS publik); kosongkan bila ingin memakai polling.
3. Salin Channel secret (rspch_…) yang muncul — hanya ditampilkan sekali. Simpan di server Anda sebagai variabel lingkungan, mis. RSPOND_CHANNEL_SECRET. Jangan taruh di aplikasi HP atau kode browser.
4. Salin Endpoint pesan masuk (…/api/channel/ch_…/messages).
5. Pasang bot ke koneksi API di menu Bot.

2. Mengirim pesan pengguna ke Rspond

POST ke endpoint pesan masuk dengan header Authorization: Bearer <channel secret> dan body JSON:

curl -X POST "https://rspond.id/api/channel/ch_KUNCI_ANDA/messages" \
  -H "Authorization: Bearer $RSPOND_CHANNEL_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"u-1024","name":"Budi","text":"Kopi gayo masih ada?","message_id":"chat-88121"}'

Respons

3. Menerima balasan lewat webhook

Setiap balasan bot, AI, atau tim dikirim sebagai POST JSON ke URL webhook Anda. Header Rspond-Signature berisi t (waktu UNIX) dan v1 = HMAC-SHA256(channel secret, "t.body") dalam hex. Periksa tanda tangan sebelum memakai isinya, dan tolak bila t lebih dari 5 menit.

POST https://sistem-anda.com/rspond/webhook
Content-Type: application/json
Rspond-Signature: t=1792390000,v1=5d41402abc4b2a76b9719d911017c592...

{
  "event": "message.reply",
  "id": "msg_3f1c2a5e-8b7d-4c1e-9a0f-2d6b7e8c9a10",
  "user_id": "u-1024",
  "text": "Ada, Kak! Kopi Arabika Gayo 250g harganya Rp85.000. Mau saya pesankan?",
  "buttons": [
    { "id": "pesan", "label": "Pesan sekarang" },
    { "id": "admin", "label": "Bicara dengan admin" }
  ],
  "media": null,
  "sent_at": "2026-10-19T03:01:12.000Z"
}

• Balas dengan status 2xx dalam 8 detik. Gagal/timeout/5xx diulang sampai 3 kali (langsung, +1 detik, +3 detik); 4xx tidak diulang.
• Bila semua percobaan gagal, pesan ditandai gagal di inbox Rspond — tim Anda melihatnya. Balasan juga tetap bisa diambil lewat polling.
• media.url berlaku ±1 jam — unduh dan simpan di sistem Anda bila perlu ditampilkan lebih lama.
• event "message.reply" = balasan bot/AI/tim; event "message.proactive" = pesan yang Anda minta sendiri lewat /send (bagian 5) — abaikan bila aplikasi Anda sudah menampilkannya.

Contoh memeriksa tanda tangan

import crypto from "node:crypto";
import express from "express";

const app = express();

// Body MENTAH dibutuhkan untuk memeriksa tanda tangan.
app.post("/rspond/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Rspond-Signature") ?? "";
  const { t, v1 = "" } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const body = req.body.toString("utf8");
  const expected = crypto
    .createHmac("sha256", process.env.RSPOND_CHANNEL_SECRET)
    .update(`${t}.${body}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const valid = v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
  if (!fresh || !valid) return res.sendStatus(401);

  const reply = JSON.parse(body);
  // tampilkan balasan ke pengguna: reply.user_id, reply.text, reply.buttons, reply.media
  res.sendStatus(200);
});

4. Tombol pilihan (menu Chatbot)

Bila balasan berisi buttons, tampilkan sebagai tombol. Saat pengguna mengetuk salah satunya, kirim pesan dengan payload = id tombol (text opsional, untuk ditampilkan di inbox):

{ "user_id": "u-1024", "payload": "pesan", "text": "Pesan sekarang" }

5. Pesan proaktif (bisnis memulai)

Ingin mengabari pengguna lebih dulu — pesanan dikirim, janji temu besok, tagihan jatuh tempo? POST ke endpoint …/send (ganti /messages di URL dengan /send), header Authorization sama. Rspond mencatatnya di percakapan (tampil "Sistem Anda (API)" di inbox, dan AI memahaminya saat pengguna membalas), lalu mengirimnya ke webhook Anda dengan event "message.proactive" — atau tersedia lewat polling.

curl -X POST "https://rspond.id/api/channel/ch_KUNCI_ANDA/send"   -H "Authorization: Bearer $RSPOND_CHANNEL_SECRET"   -H "Content-Type: application/json"   -d '{"user_id":"u-1024","text":"Pesanan #88 sudah dikirim via JNE (resi JN123456).","buttons":[{"id":"lacak","label":"Lacak paket"}],"message_id":"order-88-shipped"}'

Respons

{ "ok": true, "duplicate": false, "id": "out:u-1024:order-88-shipped", "conversation_id": "…" }

• Respons 200 berisi id pesan (sama dengan id di webhook). 502 = webhook Anda gagal menerima; pesan tercatat gagal di inbox — kirim ulang dengan message_id yang sama.
• Tidak memakai kuota balasan AI dan tidak mengubah status percakapan; bila pengguna membalas, bot/AI atau tim melanjutkan seperti biasa.
• Batas 120 pesan proaktif per menit per workspace (429 + Retry-After). Untuk promosi massal ke banyak orang, kirim bertahap.
• Server webhook Anda harus bisa melayani request lain selama memanggil /send — Rspond mengirim webhook-nya sebelum /send menjawab.

6. Foto

Kirim foto pengguna (mis. bukti transfer) sebagai data URL. Foto dari bot/tim datang di media.url pada webhook.

{ "user_id": "u-1024", "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg…", "text": "Ini bukti transfernya" }

7. Alternatif: polling (tanpa webhook)

Bila server Anda tidak bisa menerima webhook, ambil riwayat percakapan satu pengguna dengan GET ke endpoint yang sama. Pakai after (waktu ISO dari pesan terakhir yang sudah Anda punya) supaya hanya pesan baru yang dikembalikan; maks 100 per panggilan. Disarankan setiap 3–5 detik saat pengguna sedang membuka chat.

curl "https://rspond.id/api/channel/ch_KUNCI_ANDA/messages?user_id=u-1024&after=2026-10-19T03:00:00Z" \
  -H "Authorization: Bearer $RSPOND_CHANNEL_SECRET"

Contoh

{
  "messages": [
    { "id": "u-1024:chat-88121", "direction": "in", "text": "Kopi gayo masih ada?",
      "buttons": null, "media": null, "created_at": "2026-10-19T03:01:05.000Z" },
    { "id": "msg_3f1c2a5e-…", "direction": "out", "text": "Ada, Kak! …",
      "buttons": [{ "id": "pesan", "label": "Pesan sekarang" }], "media": null,
      "created_at": "2026-10-19T03:01:12.000Z" }
  ]
}

Tips & batasan

• Simpan channel secret hanya di server. Bocor? Buat ulang di Channel → API — secret lama langsung tidak berlaku.
• Satu user_id = satu kontak di Rspond. Pakai id permanen dari database Anda, bukan id sesi.
• Tim bisa mengambil alih percakapan dari inbox atau aplikasi HP Rspond; balasan tim dikirim ke webhook yang sama.
• Setiap balasan AI memakai kuota balasan AI paket workspace (dipakai bersama channel lain).
• Batas laju melindungi kuota Anda dari banjir pesan; kirim ulang setelah Retry-After bila mendapat 429.