Tekan Enter.
Dapatkan data Anda.

Mulai cepat

Tiga langkah dari nol ke jawaban pertama. Setiap permintaan terikat pada satu widget dan diautentikasi dengan token pembawa.

1. Keluarkan tokenDasbor → Token API: nama, masa berlaku opsional, dan cakupan yang Anda perlukan. Sebuah token dimiliki tepat oleh satu widget. Token teks biasa ditampilkan sekali; Smartbtn hanya menyimpan hash satu arah, sehingga token yang hilang tidak dapat dipulihkan — hanya dicabut dan diterbitkan kembali.
2. Aktifkan API widgetDi pengaturan widget, aktifkan «Izinkan API widget (JS dan REST)». Menerbitkan token tidak mengubah hal ini untuk Anda.
3. Kirim permintaan pertamaToken hanya masuk ke header Otorisasi — tidak pernah masuk ke URL.

# daftar obrolan widget
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · paginasi kursor
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — di halaman terakhir
}

Otentikasi

Tiga jalur, tergantung siapa memanggil siapa. Akses ditolak secara default: tidak ada cakupan — tidak ada panggilan.

Peralihan yang dilupakan orang

«Izinkan API widget (JS dan REST)» di pengaturan widget akan membuka REST API dan widget JS API. Menerbitkan token tidak mengaktifkannya. Cakupan kunci yang ada dapat diedit di dasbor (token API → kunci → Edit cakupan) tanpa menerbitkan ulang — integrasi tetap berfungsi.

Preset

Lingkup

53 cakupan rute, ditambah satu kondisional dan satu cadangan. Permintaan berhasil hanya jika token tersebut memiliki cakupan rute (atau alternatif yang terdaftar).

Titik akhir

Seluruh permukaan publik dalam satu daftar. Filter berdasarkan sumber daya, cari berdasarkan jalur, klik baris untuk menyalin ikal yang sudah jadi.

Jalur bersifat relatif terhadap https://smartbtn.me/api. Penulisan memerlukan Content‑Type: application/json dan X‑Smartbtn‑Idempotency‑Key. Grup compat adalah lapisan kompatibilitas untuk tim yang berpindah dari platform chat lain.

Webhook

POST JSON yang ditandatangani ke URL Anda setiap kali peristiwa berlangganan terjadi. Kelola langganan melalui /v1/webhook‑subscriptions atau di dasbor.

{
  "id": "evt_01JAB3K9Q7",
  "type": "ticket.created",
  "data": {
    "button_guid": "b_3f9c2e",
    "ticket_number": 10482,
    "chat_id": 48211,
    "client_id": 9134,
    "reason": "human_request",
    "priority": "high",
    "sla_hours": 4,
    "source": "chat",
    "created_at": "2026-10-17T10:15:00+03:00"
  }
}

Header pengiriman

Verifikasi tanda tangan

HMAC‑SHA256 dari isi mentah (byte yang diterima, sebelum penguraian JSON) dengan rahasia titik akhir Anda; bandingkan dalam waktu yang konstan. Rahasianya ditampilkan satu kali, saat langganan dibuat; putar dengan POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · Misalnya, rahasianya adalah placeholder
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=v1:' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// PHP
$expected = 'sha256=v1:' . hash_hmac('sha256', file_get_contents('php://input'), $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SMARTBTN_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

Coba lagi dan pesan

• Hingga 4 percobaan (pengiriman pertama ditambah 3 percobaan ulang), backoff min(60, 2^attempt × 5) s — sekitar 10, 20, 40 detik.
• Non‑2xx atau batas waktu dihitung sebagai upaya yang gagal. Pengiriman yang gagal dapat dikirim ulang dengan POST /v1/webhook‑subscriptions/{id}/redeliver — kunci idempotensi yang sama, id pengiriman baru.
• Pengiriman dilakukan setidaknya satu kali dan tidak dipesan. Muatannya minimal — id, bukan catatan lengkap; ambil detail melalui REST API.

JS API

Sampaikan apa yang sudah Anda ketahui tentang pengunjung langsung ke agen. Panggilan hanya diterima dari domain yang diatur dalam pengaturan widget.

smartbtn_widget_api.setContactInfo(info)

Mengatur data kontak pengunjung. Agen melihatnya seolah‑olah pengunjung mengisi formulir perkenalan. Nama, telepon, dan email memainkan peran khusus di Smartbtn — oleh karena itu merupakan metode terpisah.

Smartbtn_api.setClientInfo({
  name: "Alex Morgan",
  email: "email@example.com",
  phone: "+17584987855",
  description: "Description text"
});

smartbtn_widget_api.setCustomData(fields)

Data tambahan apa pun untuk panel info di sebelah kanan aplikasi agen. Sebut saja sesering yang Anda suka — dalam dialog terbuka, panel diperbarui secara real‑time. Bidang ditampilkan dalam urutan array.

Smartbtn_api.setClientCustomData([
  { title: "Order", content: "#10482 · 3 items", link: "https://shop.example/orders/10482" },
  { title: "Actions", content: "Open customer profile", link: "https://crm.example/c/9134" }
]);

smartbtn_widget_api.setSkin(skin, opts) · open() · close()

Ganti tema widget dengan cepat tanpa memuat ulang halaman (klasik, minimal, capsule, liquid) atau mengontrol jendela obrolan secara terprogram. Untuk penyesuaian permanen per proyek, teruskan kolom yang sama ke PATCH /v1/widget/settings.

// JS API · ganti kulit pada halaman secara real time
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "Balasan dalam ~1 detik" });

// REST API · PATCH /v1/widget/settings (ruang lingkup widget:write)
{
  "skin": "minimal",
  "widget_header_align": "center",
  "widget_show_operator_avatars": false,
  "widget_show_tabs_bar": false,
  "chat_bg": "#FAF8F5",
  "capsule_title": "Smartbtn AI",
  "capsule_subtitle": "Online 24/7"
}

Support‑agent API

Agen dukungan otomatis mengerjakan antrian tiket dan obrolan pelanggan: menerima obrolan, menjawab sesuai operator dukungan manusia Anda, menutup tiket. Mati hingga pemilik widget menyalakannya.

curl -X POST https://smartbtn.me/api/v1/support/chats/48211/reply \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $(uuidgen)" \
  -d '{"text":"Selesai, akses telah dipulihkan."}'

API AI

Semua yang dilakukan bagian AI di dasbor: asisten, kunci penyedia Anda sendiri, basis pengetahuan, pembelajaran mandiri dengan rollback, keinginan, masalah, sinyal permintaan, dan asisten di dalam aplikasi Anda.

Batasan tarif

Per token, ada dua penghitung: baca dan tulis dihitung secara terpisah, sehingga jajak pendapat tidak pernah menghabiskan anggaran penulisan.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "status": 429, "title": "Too Many Requests", "reason": "rate_limited" }

/v1/ai/assistant/tickets/status dan /v1/ai/assistant/account‑link memiliki penghitungnya sendiri; API agen dukungan dapat memiliki penggantian per widget.

Kesalahan

Setiap kesalahan adalah application/problem+json RFC‑7807: status dan alasan yang dapat dibaca mesin, detail yang dapat dibaca manusia.

HTTP/1.1 403 · Content-Type: application/problem+json
{
  "type": "https://smartbtn.me/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Token lacks scope chats:write.",
  "required_scopes": [
    "chats:write"
  ],
  "hint": "Dashboard → API tokens → key → Edit scopes"
}

Nama badan yang diperlukan_scopes dan di mana memberikannya. Tidak perlu mengeluarkan ulang kuncinya.

Idempotensi

Jaringan gagal. Kunci membuat percobaan ulang penulisan menjadi aman: operasi yang sama tidak pernah diterapkan dua kali.

• Kirim X‑Smartbtn‑Idempotency‑Key pada setiap POST / PATCH / PUT / DELETE: UUID baru untuk operasi baru, kunci yang sama untuk mencoba ulang operasi yang sama.
• Operasi yang ditandai x‑idempotensi: diperlukan di OpenAPI: tanpa kunci → 400, kunci digunakan kembali dalam waktu 24 jam → 409 (tidak berhasil disimpan dalam cache).
• Tidak yakin itu berhasil? Baca negara bagiannya terlebih dahulu. Jangan pernah mengganti kunci secara otomatis; hormati Coba Lagi‑Setelah.
• 502 dari penyedia upstream melepaskan kunci — coba lagi dengan kunci yang sama.

KEY=$(uuidgen)
curl -X PATCH https://smartbtn.me/api/v1/widget/settings \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $KEY" \
  -d '{"language":"ru"}'
# kesalahan jaringan? ulangi dengan $KEY yang sama

Changelog

Perubahan pada API publik dan webhook pada tahun 2026. Segala sesuatu di bawah bersifat aditif dan tetap berada di v1.

plugin WordPress

Widget di situs WordPress tanpa menyentuh kode tema.

Contoh kode

Cantumkan setiap obrolan dengan aktivitas sejak jajak pendapat terakhir Anda — ikuti kursor hingga akhir.

# halaman pertama
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "updated_since=2026-10-17T09:00:00+03:00"

# next — dengan next_cursor dari respons
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"