הקש על Enter.
קבל את הנתונים שלך.

התחלה מהירה

שלושה שלבים מאפס לתשובה הראשונה. כל בקשה קשורה לווידג'ט אחד ומאומתת עם אסימון נושא.

1. הנפק אסימוןלוח מחוונים ← אסימוני API: שם, תפוגה אופציונלית וההיקפים הדרושים לך. אסימון שייך לווידג'ט אחד בדיוק. אסימון הטקסט הפשוט מוצג פעם אחת; Smartbtn מאחסנת חשיש חד-כיווני בלבד, כך שלא ניתן לשחזר אסימון שאבד - רק לבטל ולהנפיק מחדש.
2. הפעל את ה-API של הווידג'טבהגדרות הווידג'ט, הפעל את "אפשר API של יישומון (JS ו-REST)". הנפקת אסימון לא תהפוך את המתג הזה עבורך.
3. שלח את הבקשה הראשונההאסימון נכנס רק לכותרת Authorization - לעולם לא לכתובת האתר.

# רשום את הצ'אטים של הווידג'ט
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 והן את ה-API של ה-widget JS. הנפקת אסימון אינה מאפשרת זאת. ניתן לערוך את ההיקפים של מפתח קיים בלוח המחוונים (אסימוני API → מקש → ערוך היקפים) בלי להנפיק מחדש אותו - האינטגרציות ממשיכות לעבוד.

הגדרות קבועות מראש

היקפים

53 היקפי מסלול, פלוס אחד מותנה ואחד שמור. בקשה מצליחה רק אם האסימון מחזיק בהיקף המסלול (או חלופה רשומה).

נקודות קצה

כל השטח הציבורי ברשימה אחת. סנן לפי משאב, חפש לפי נתיב, לחץ על שורה כדי להעתיק תלתל מוכן.

הנתיבים הם יחסיים ל-https://smartbtn.me/api. כתיבה צריכה Content‑Type: application/json ו-X‑Smartbtn‑Idempotency‑Key. קבוצת compat היא שכבת תאימות לצוותים העוברים מפלטפורמת צ'אט אחרת.

Webhooks

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 ניסיונות חוזרים), השבתה min(60, 2^attempt × 5) s - בערך 10, 20, 40 שניות.
• Non‑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":"בוצע, הגישה שוחזרה."}'

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 יש מונים משלהם; ל-support‑agent 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"
}

שמות הגוף required_scopes והיכן להעניק אותם. אין צורך להנפיק מחדש את המפתח.

אידמונטיות

רשתות נכשלות. מפתח הופך כתיבה שנוסתה לבטוחה: אותה פעולה לעולם אינה מופעלת פעמיים.

• שלח X‑Smartbtn‑Idempotency‑Key בכל POST / PATCH / PUT / DELETE: UUID חדש לפעולה חדשה, אותו מפתח עבור ניסיון חוזר של אותה אחת.
• פעולות המסומנות x‑idempotency: required ב-OpenAPI: ללא מפתח → 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

שינויים בממשק ה-API הציבורי וב-webhooks בשנת 2026. הכל למטה הוא תוסף ונשאר ב-v1.

תוסף וורדפרס

הווידג'ט באתר וורדפרס מבלי לגעת בקוד הנושא.

דוגמאות קוד

רשום כל צ'אט עם פעילות מאז הסקר האחרון שלך - בצע את הסמן עד הסוף.

# עמוד ראשון
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 — עם next_cursor מהתגובה
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"