Enter tugmasini bosing.
Maʼlumotlaringizni oling.

Tez boshlash

Noldan birinchi javobgacha uch qadam. Har bir so'rov bitta vidjetga bog'langan va tashuvchi tokeni bilan autentifikatsiya qilingan.

1. Token chiqaringBoshqaruv paneli → API tokenlari: nom, ixtiyoriy amal qilish muddati va sizga kerak bo‘lgan qamrovlar. Token aynan bitta vidjetga tegishli. Oddiy matnli token bir marta ko'rsatiladi; Smartbtn faqat bir tomonlama xeshni saqlaydi, shuning uchun yo'qolgan tokenni tiklab bo'lmaydi - faqat bekor qilinadi va qayta chiqariladi.
2. Vidjet API‑ni yoqingVidjet sozlamalarida "Vidjet API‑ga ruxsat berish (JS va REST)" ni yoqing. Token chiqarish bu kalitni siz uchun aylantirmaydi.
3. Birinchi so'rovni yuboringToken faqat Authorization sarlavhasiga kiradi - hech qachon URL manziliga kirmaydi.

# vidjet chatlarini ro'yxatga kiriting
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · kursorni sahifalash
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — oxirgi sahifada
}

Autentifikatsiya

Kim kimni chaqirganiga qarab uchta yo'l. Kirish sukut bo'yicha rad etiladi: qamrov yo'q - qo'ng'iroq yo'q.

O'zgartiruvchi odamlar unutishadi

Vidjet sozlamalaridagi «Vidjet API (JS va REST) ​​ruxsat berish» REST API va vidjet JS API ni ochadi. Tokenni chiqarish uni faollashtirmaydi. Mavjud kalitning qamrovini asboblar panelida tahrirlash mumkin (API tokenlari → kalit → Qo‘llanish doirasini tahrirlash) qayta chiqarmasdan - integratsiya ishlashda davom etadi.

Oldindan sozlash

Qo'llash sohalari

53 ta marshrut doirasi, bundan tashqari bitta shartli va bitta zaxiralangan. Agar token marshrut doirasini (yoki sanab o'tilgan muqobilni) ushlab tursa, so'rov muvaffaqiyatli bo'ladi.

Yakuniy nuqtalar

Bir ro'yxatda butun jamoatchilik yuzasi. Resurs bo'yicha filtrlang, yo'l bo'yicha qidiring, tayyor jingalakni nusxalash uchun qatorni bosing.

Yo'llar https://smartbtn.me/api ga nisbatan. Yozish uchun Content‑Type: application/json va X‑Smartbtn‑Idempotency‑Key kerak. compat guruhi boshqa chat platformasidan harakatlanuvchi jamoalar uchun moslik qatlamidir.

Webhuklar

Obuna boʻlgan voqea sodir boʻlganda URL manzilingizga imzolangan JSON POST. Obunalarni /v1/webhook‑subscriptions yoki asboblar paneli orqali boshqaring.

{
  "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"
  }
}

Yetkazib berish sarlavhalari

Imzoni tekshirish

xom korpusning HMAC‑SHA256 (qabul qilingan baytlar, JSON tahlilidan oldin) oxirgi nuqta siringiz bilan; doimiy vaqtda solishtiring. Yashirin obuna yaratilganda bir marta ko'rsatiladi; uni POST /v1/webhook‑subscriptions/{id}/rotate‑secret bilan aylantiring.

// Node.js · masalan, sir o‘rin tutuvchidir
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; }

Qayta urinish va buyurtma

• 4 urinishgacha (birinchi yuborish plyus 3 marta urinish), orqaga qaytish min(60, 2^urinish × 5) s — taxminan 10, 20, 40 s.
• 2xx bo'lmagan yoki vaqt tugashi muvaffaqiyatsiz urinish sifatida hisoblanadi. Muvaffaqiyatsiz yetkazib berishlarni POST /v1/webhook‑subscriptions/{id}/redeliver bilan qayta yuborish mumkin — bir xil identifikator kaliti, yangi yetkazib berish identifikatori.
• Yetkazib berish kamida bir marta amalga oshiriladi va buyurtma berilmagan. Foydali yuklar minimal - to'liq yozuvlar emas, idlar; REST API orqali tafsilotlarni olish.

JS API

Mehmon haqida allaqachon bilganingizni to'g'ridan‑to'g'ri agentga uzating. Qo'ng'iroqlar faqat vidjet sozlamalarida o'rnatilgan domendan qabul qilinadi.

smartbtn_widget_api.setContactInfo(info)

Tashrifchining aloqa ma'lumotlarini o'rnatadi. Agent buni xuddi tashrifchi kirish shaklini to'ldirgandek ko'radi. Smartbtn‑da ism, telefon va elektron pochta alohida rol o'ynaydi - shuning uchun alohida usul.

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

smartbtn_widget_api.setCustomData(fields)

Agent ilovasining oʻng tomonidagi maʼlumotlar paneli uchun qoʻshimcha maʼlumotlar. Istaganingizcha tez‑tez qo'ng'iroq qiling - ochiq muloqot oynasida panel real vaqtda yangilanadi. Maydonlar massiv tartibida ko'rsatilgan.

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()

Vidjet mavzusini sahifani qayta yuklamasdan tezda almashtiring (klassik, minimal, capsule, liquid) yoki chat oynasini dasturiy tarzda boshqaring. Har bir loyihani doimiy sozlash uchun bir xil maydonlarni PATCH /v1/widget/settings ga o'tkazing.

// JS API · real vaqtda sahifadagi terini almashtirish
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "~1 soniyada javoblar" });

// REST API · PATCH /v1/widget/settings (qamrovi 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": "Onlayn 24/7"
}

Support‑agent API

Avtomatlashtirilgan qo'llab‑quvvatlash agenti chiptalar navbatini va mijozlar suhbatlarini ishlaydi: suhbatni qabul qiladi, sizning insoniy yordam operatoringiz sifatida javob beradi, chiptani yopadi. Vidjet egasi uni yoqmaguncha oʻchiring.

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":"Bajarildi, kirish tiklandi."}'

AI API

Boshqaruv panelining AI bo'limi bajaradigan hamma narsa: yordamchilar, shaxsiy provayder kalitlari, bilimlar bazasi, orqaga qaytish bilan o'z‑o'zini o'rganish, istaklar, muammolar, talab signallari va ilovangiz ichidagi yordamchi.

Tarif cheklovlari

Token uchun ikkita hisoblagich: o'qish va yozish bir‑biridan ajratiladi, shuning uchun so'rov hech qachon yozish byudjetini yemaydi.

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 va /v1/ai/assistant/account‑link o'z hisoblagichlariga ega; qo'llab‑quvvatlash agenti API har bir vidjetni bekor qilishi mumkin.

Xatolar

Har bir xato RFC‑7807 application/problem+json: mashina o‘qiy oladigan holat va sabab, odam o‘qiy oladigan tafsilot.

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"
}

Tana shartli_skoplarni va ularni qayerda berishni nomlaydi. Kalitni qayta chiqarish shart emas.

Idroksizlik

Tarmoqlar muvaffaqiyatsiz. Kalit qayta urinilgan yozishni xavfsiz qiladi: bir xil operatsiya hech qachon ikki marta qo'llanilmaydi.

• Har bir POST / PATCH / PUT / DELETE da X‑Smartbtn‑Idempotency‑Key yuboring: yangi operatsiya uchun yangi UUID, bir xilni qayta urinish uchun bir xil kalit.
• OpenAPI da x‑idempotency: required deb belgilangan operatsiyalar: kalit yoʻq → 400, kalit 24 soat ichida qayta ishlatiladi → 409 (keshlangan muvaffaqiyat emas).
• Ishonchingiz komil emasmi? Avval davlatni o'qing. Hech qachon kalitni avtomatik ravishda o'zgartirmang; Qayta urinish‑Keyin hurmat qiling.
• Yuqori oqim provayderidan 502 kalitni chiqaradi — xuddi shu kalit bilan qayta urinib ko'ring.

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"}'
# tarmoq xatosi? bir xil $KEY bilan takrorlang

Changelog

2026‑yilda umumiy API va vebhuklarga o‘zgartirishlar. Quyida hamma narsa qo‘shimcha va v1 da qoladi.

WordPress plagin

Mavzu kodiga tegmasdan WordPress saytidagi vidjet.

Kod namunalari

Oxirgi so'rovingizdan keyingi har bir chatni ro'yxatlang - kursorni oxirigacha kuzatib boring.

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

# keyingi — javobdan keyingi_kursor bilan
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"