Panduan · Channel & Integrasi

Menyambungkan sistem Anda sendiri

Untuk platform yang belum kami dukung langsung. Butuh bantuan tim IT sekali saja; sesudah tersambung, tim CS memakainya seperti saluran lain.

Untuk siapa panduan ini

Untuk tim IT Anda. Pemilik usaha cukup membuat salurannya di halaman Channels, lalu menyerahkan tiga hal yang muncul di layar terakhir kepada tim IT.

Panduan ini dipakai kalau chat Anda ada di tempat yang belum kami dukung langsung: Lazada, sistem tiket kantor, aplikasi buatan sendiri, atau penyedia yang sudah punya izin resmi ke marketplace tertentu.

Kenapa tidak kami sambungkan sendiri saja? Untuk sebagian platform, aksesnya menuntut persetujuan yang hanya diberikan kepada pihak yang punya hubungan resmi dengan platform itu. Dengan cara ini, Anda tidak perlu menunggu persetujuan yang mungkin tidak pernah datang.

Langkah 1 — Buat salurannya

Buka SALURAN & TIM → Channels, tekan + Tambah Channel, pilih Sambungan sendiri. Isi namanya (mis. "Chat Lazada"). Kolom alamat balasan boleh dikosongkan dulu.

Layar terakhir menampilkan tiga hal. Salin ketiganya — dua di antaranya hanya muncul sekali:

| Yang muncul | Untuk apa | |---|---| | Alamat kirim pesan masuk | tujuan sistem Anda mengirim chat masuk | | Kunci pesan MASUK | menandatangani kiriman Anda supaya kami tahu itu benar dari Anda | | Kunci pesan KELUAR | memeriksa bahwa balasan yang tiba benar dari kami |

Langkah 2 — Kirim pesan masuk ke kami

Tiap ada chat baru di sistem Anda, kirim satu permintaan seperti ini. Perintah di bawah bisa langsung dijalankan — ganti tiga nilai di baris pertama dengan milik Anda.

Kirim satu pesan masuk (bisa langsung dijalankan)

ALAMAT="https://contoh-domain.anda/_api/webhooks/custom/GANTI_ID_SALURAN"
KUNCI="cin_GANTI_DENGAN_KUNCI_MASUK_ANDA"

BADAN='{"from":"628123456789","name":"Budi","text":"Halo, pesanan saya sudah dikirim?"}'
STEMPEL=$(date +%s)
TANDA=$(printf '%s' "$STEMPEL.$BADAN" | openssl dgst -sha256 -hmac "$KUNCI" | awk '{print $2}')

curl -X POST "$ALAMAT" \
  -H "Content-Type: application/json" \
  -H "X-BantuCS-Signature: t=$STEMPEL,v1=$TANDA" \
  -d "$BADAN"

Balasan yang benar: 202 dengan isi {"ok":true,"diterima":true}.

Tiga hal yang paling sering membuat gagal

Menandatangani badan yang sudah diurai ulang. Tanda tangan dihitung dari

badan persis seperti yang dikirim. Mengurai JSON lalu menyusunnya kembali mengubah satu byte, dan tanda tangannya tidak akan pernah cocok.

Jam server meleset. Kiriman yang selisihnya lebih dari 5 menit ditolak.

Itu disengaja: tanpa batas waktu, kiriman lama yang pernah sah bisa direkam lalu dikirim ulang kapan saja.

Urutan yang ditandatangani. Yang benar: stempel + titik + badan.

Setiap penolakan menyebutkan sebabnya di badan balasan — baca pesannya, jangan menebak.

Langkah 3 — Terima balasan dari kami (opsional)

Kalau balasan harus kembali ke sistem Anda, isi alamat balasan di pengaturan saluran. Kami akan memanggilnya dengan bentuk tanda tangan yang sama persis, memakai kunci KELUAR — jadi tim Anda cukup menulis satu pemeriksa untuk dua arah.

Contoh memeriksa balasan yang tiba (Node.js)

import { createHmac, timingSafeEqual } from 'node:crypto';

export function sahkah(header, badanMentah, kunciKeluar) {
  const bagian = Object.fromEntries(header.split(',').map((x) => x.split('=')));

  // Tolak kiriman kedaluwarsa — tanpa ini, kiriman lama bisa diputar ulang.
  if (Math.abs(Date.now() / 1000 - Number(bagian.t)) > 300) return false;

  const harapan = createHmac('sha256', kunciKeluar)
    .update(`${bagian.t}.${badanMentah}`)
    .digest('hex');

  const a = Buffer.from(harapan);
  const b = Buffer.from(bagian.v1 ?? '');
  return a.length === b.length && timingSafeEqual(a, b);
}

Badan yang kami kirim:

{
  "channel_id": "…",
  "conversation_id": "…",
  "to": "628123456789",
  "text": "Halo Budi, pesanan Anda sudah dikirim kemarin.",
  "sent_at": "2026-08-06T10:20:00.000Z"
}

Balas 2xx bila diterima. Sistem Anda boleh mengembalikan {"message_id":"…"} supaya pesannya bisa dicocokkan nanti — tidak wajib.

Cara tahu berhasil

Pesan uji dari langkah 2 muncul di Inbox dalam beberapa detik.
Membalas dari Inbox membuat sistem Anda menerima panggilan (bila alamat balasan diisi).
Kiriman tanpa tanda tangan, atau dengan tanda tangan salah, ditolak 401 —

dan pesan penolakannya menyebutkan sebabnya.

Tips

Simpan kuncinya di tempat rahasia, bukan di dalam kode yang ikut ter-commit.
Kunci masuk dan keluar sengaja berbeda. Kalau disamakan, siapa pun yang bisa

menerima dari kami otomatis bisa mengirim sebagai Anda.

Satu saluran per sumber. Chat Lazada dan sistem tiket sebaiknya dua saluran

terpisah supaya bisa dibedakan di Inbox dan dimatikan sendiri-sendiri.

Kunci hilang? Buat saluran baru — kami tidak bisa menampilkannya lagi, dan itu

memang disengaja.

Masih ada yang bingung?

Tim support kami siap bantu di jam kerja WIB. Jelaskan kendalamu, kami arahkan langkah demi langkah.

Untuk siapa panduan ini

Untuk tim IT Anda. Pemilik usaha cukup membuat salurannya di halaman Channels, lalu menyerahkan tiga hal yang muncul di layar terakhir kepada tim IT.

Kenapa tidak kami sambungkan sendiri saja? Untuk sebagian platform, aksesnya menuntut persetujuan yang hanya diberikan kepada pihak yang punya hubungan resmi dengan platform itu. Dengan cara ini, Anda tidak perlu menunggu persetujuan yang mungkin tidak pernah datang.

Langkah 1 — Buat salurannya

Buka SALURAN & TIM → Channels, tekan + Tambah Channel, pilih Sambungan sendiri. Isi namanya (mis. "Chat Lazada"). Kolom alamat balasan boleh dikosongkan dulu.

Layar terakhir menampilkan tiga hal. Salin ketiganya — dua di antaranya hanya muncul sekali:

ALAMAT="https://contoh-domain.anda/_api/webhooks/custom/GANTI_ID_SALURAN" KUNCI="cin_GANTI_DENGAN_KUNCI_MASUK_ANDA" BADAN='{"from":"628123456789","name":"Budi","text":"Halo, pesanan saya sudah dikirim?"}' STEMPEL=$(date +%s) TANDA=$(printf '%s' "$STEMPEL.$BADAN" | openssl dgst -sha256 -hmac "$KUNCI" | awk '{print $2}') curl -X POST "$ALAMAT" \ -H "Content-Type: application/json" \ -H "X-BantuCS-Signature: t=$STEMPEL,v1=$TANDA" \ -d "$BADAN"

import { createHmac, timingSafeEqual } from 'node:crypto'; export function sahkah(header, badanMentah, kunciKeluar) { const bagian = Object.fromEntries(header.split(',').map((x) => x.split('='))); // Tolak kiriman kedaluwarsa — tanpa ini, kiriman lama bisa diputar ulang. if (Math.abs(Date.now() / 1000 - Number(bagian.t)) > 300) return false; const harapan = createHmac('sha256', kunciKeluar) .update(`${bagian.t}.${badanMentah}`) .digest('hex'); const a = Buffer.from(harapan); const b = Buffer.from(bagian.v1 ?? ''); return a.length === b.length && timingSafeEqual(a, b); }

Tips

Simpan kuncinya di tempat rahasia, bukan di dalam kode yang ikut ter-commit.

Kunci masuk dan keluar sengaja berbeda. Kalau disamakan, siapa pun yang bisa

menerima dari kami otomatis bisa mengirim sebagai Anda.

Satu saluran per sumber. Chat Lazada dan sistem tiket sebaiknya dua saluran

terpisah supaya bisa dibedakan di Inbox dan dimatikan sendiri-sendiri.

Kunci hilang? Buat saluran baru — kami tidak bisa menampilkannya lagi, dan itu

memang disengaja.