Enter пернесін басыңыз.
Деректерді алыңыз.

Жылдам бастау

Нөлден бірінші жауапқа дейін үш қадам. Әрбір сұрау бір виджетпен байланыстырылған және жеткізуші таңбалауышымен аутентификацияланған.

1. Токен шығаруБақылау тақтасы → API токендері: атау, қосымша жарамдылық мерзімі және сізге қажет аумақтар. Токен дәл бір виджетке жатады. Қарапайым мәтіндік таңбалауыш бір рет көрсетіледі; Smartbtn тек бір жақты хэшті сақтайды, сондықтан жоғалған таңбалауышты қалпына келтіру мүмкін емес — тек күші жойылып, қайта шығарылады.
2. API виджеттерін қосыңызВиджет параметрлерінде «Виджет API (JS және REST) ​​рұқсат беру» параметрін қосыңыз. Токен шығару бұл қосқышты сіз үшін аудармайды.
3. Бірінші сұрауды жіберіңізТокен тек Authorization тақырыбына өтеді — ешқашан URL мекенжайына кірмейді.

# виджеттің сөйлесулерін тізімдеңіз
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · курсорды беттеу
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — соңғы бетте
}

Аутентификация

Кім кімге қоңырау шалатынына байланысты үш жол. Қатынас әдепкі бойынша қабылданбайды: ауқым жоқ — қоңырау жоқ.

Ауыстырушы адамдар ұмытады

Виджет параметрлеріндегі «Виджет API (JS және REST) ​​рұқсат беру» REST API және виджет JS API екеуін де ашады. Токен шығару оны іске қоспайды. Қолданыстағы кілттің аумақтарын бақылау тақтасында өңдеуге болады (API таңбалауыштары → кілт → Аумақтарды өңдеу) қайта шығарусыз оны — интеграциялар жұмысын жалғастырады.

Алдын ала орнатулар

Қолдану аумақтары

53 бағыт ауқымы, плюс біреуі шартты және біреуі резервтелген. Сұрау таңбалауыш маршрут ауқымын (немесе тізімделген балама) ұстаған жағдайда ғана орындалады.

Соңғы нүктелер

Бүкіл қоғамдық беті бір тізімде. Дайын бұйраны көшіру үшін ресурс бойынша сүзіңіз, жол бойынша іздеңіз, жолды басыңыз.

Жолдар https://smartbtn.me/api түріне қатысты. Жазу үшін Content‑Type: application/json және X‑Smartbtn‑Idempotency‑Key қажет. compat тобы басқа чат платформасынан қозғалатын командаларға арналған үйлесімділік деңгейі болып табылады.

Вебхуктар

Жазылған оқиға орын алған сайын URL мекенжайына қол қойылған JSON POST. Жазылымдарды /v1/webhook‑subscriptions арқылы немесе бақылау тақтасында басқарыңыз.

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

Жеткізу тақырыптары

Қолтаңбаны тексеру

Соңғы нүкте құпиясымен шикі дененің HMAC‑SHA256 (алынған байт, JSON талдауына дейін); тұрақты уақытта салыстыру. Жазылым жасалған кезде құпия бір рет көрсетіледі; оны POST /v1/webhook‑subscriptions/{id}/rotate‑secret арқылы бұраңыз.

// Node.js · мысалы, құпия - толтырғыш
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; }

Қайталап көріңіз және тапсырыс беріңіз

• 4 әрекетке дейін (алғашқы жіберу плюс 3 қайталау), кері қайтару мин(60, 2^әрекет × 5) с — шамамен 10, 20, 40 с.
• 2xx емес немесе күту уақыты сәтсіз әрекет ретінде есептеледі. Сәтсіз жеткізілімдерді POST /v1/webhook‑subscriptions/{id}/redeliver арқылы қайта жіберуге болады — бірдей потенциалдық кілт, жаңа жеткізу идентификаторы.
• Жеткізу кемінде бір рет және тапсырыс берілмейді. Пайдалы жүктемелер ең аз — толық жазбалар емес, идентификаторлар; мәліметтерді REST API арқылы алу.

JS API

Келуші туралы бұрыннан білетіндеріңізді тікелей агентке беріңіз. Қоңыраулар тек виджет параметрлерінде орнатылған доменнен қабылданады.

smartbtn_widget_api.setContactInfo(info)

Келушінің байланыс деректерін орнатады. Агент оны кіруші кіріспе пішінін толтырғандай көреді. Аты, телефоны және электрондық поштасы Smartbtn‑де ерекше рөл атқарады, демек, бөлек әдіс.

Smartbtn_api.setClientInfo({
  name: «Алекс Морган»,
  email: "email@example.com",
  phone: "+17584987855",
  description: "Description text"
});

smartbtn_widget_api.setCustomData(fields)

Агент қолданбасының оң жағындағы ақпарат тақтасына арналған кез келген қосымша деректер. Оған қалағаныңызша қоңырау шалыңыз — ашық диалогтық терезеде панель нақты уақытта жаңартылады. Өрістер массив ретімен көрсетіледі.

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

Виджет тақырыбын бетті қайта жүктемей жылдам ауыстырыңыз (classic, minimal, capsule, liquid) немесе чат терезесін бағдарламалық түрде басқарыңыз. Әр жобаны тұрақты теңшеу үшін бірдей өрістерді PATCH /v1/widget/settings ішіне өткізіңіз.

// JS API · беттегі мұқабаны нақты уақытта ауыстыру
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "Жауаптар ~1 секундта" });

// REST API · PATCH /v1/widget/settings (ауқымы 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": "24/7 онлайн"
}

Support‑agent API

Автоматтандырылған қолдау агенті билет кезегін және тұтынушы чатын жұмыс істейді: чатты қабылдайды, адамдық қолдау операторы ретінде жауап береді, билетті жабады. Виджет иесі оны қосқанша өшірулі.

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":"Дайын, рұқсат қалпына келтірілді."}'

AI API

Бақылау тақтасының AI бөлімі жасайтын барлық нәрсе: көмекшілер, провайдердің жеке кілттері, білім базасы, кері қайтару арқылы өздігінен білім алу, тілектер, мәселелер, сұраныс сигналдары және қолданбадағы көмекші.

Тарифтік шектеулер

Әр таңбалауыш үшін екі есептегіш: оқу және жазу бір‑бірінен бөлек есептеледі, сондықтан сауалнама жазу бюджетін ешқашан жемейді.

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 және /v1/ai/assistant/account‑link-ның өз есептегіштері бар; API қолдау агентінде әр виджетті қайта анықтау мүмкіндігі болуы мүмкін.

Қателер

Әрбір қате RFC‑7807 application/problem+json болып табылады: машина оқылатын күй мен себеп, адам оқи алатын мәліметтер.

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

Негізгі бөлім қажет_ауқымдарды және оларды қай жерде беру керектігін атайды. Кілтті қайта шығарудың қажеті жоқ.

Импотенттілік

Желілер сәтсіз. Кілт қайталап жазуды қауіпсіз етеді: бірдей әрекет ешқашан екі рет қолданылмайды.

• Әрбір POST / PATCH / PUT / DELETE үшін X‑Smartbtn‑Idempotency‑Key жіберіңіз: жаңа операция үшін жаңа UUID, сол әрекетті қайталау үшін бірдей кілт.
• OpenAPI ішінде x‑idempotency: қажет деп белгіленген операциялар: кілт жоқ → 400, кілт 24 сағат ішінде қайта пайдаланылады → 409 (кэштелген сәтті емес).
• Оның өткеніне сенімді емессіз бе? Алдымен күйді оқыңыз. Ешқашан кілтті автоматты түрде өзгертпеңіз; Қайталау‑Кейін құрметтеу.
• Жоғары ағындық провайдерден алынған 502 кілтті шығарады — сол кілтпен әрекетті қайталаңыз.

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"}'
# желі қатесі? бірдей $KEY арқылы қайталаңыз

Changelog

2026 жылы жалпыға қолжетімді API және веб‑хуктарға енгізілген өзгерістер. Төмендегілердің барлығы қосымша болып табылады және v1 ішінде қалады.

WordPress плагині

WordPress сайтындағы виджет тақырып кодына қол тигізбестен.

Код үлгілері

Соңғы сауалнамадан кейінгі әрбір чатты тізіп көрсетіңіз — курсорды соңына дейін бақылаңыз.

# бірінші бет
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "updated_since=2026-10-17T09:00:00+03:00"

# келесі — жауаптан келесі_курсормен
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"