סקירה כללית

Quickchat AI מספקת REST API לגישה תכנותית להגדרות סוכן ה-AI, מאגר הידע, שיחות, פעולות AI ועוד.

בדיקות דוגמה אופציונליות

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

• בדיקת חיבור MCP לדוגמה. אתחלו חיבור והציגו כלים רק בנקודת הקצה של תיעוד Cloudflare או Microsoft Learn. לא מתבצעת כניסה או הרצת כלים.

אימות

כל נקודות הקצה משתמשות באימות Bearer token. כללו את אסימון ה-API בכותרת Authorization בכל בקשה:

Authorization: Bearer <API_TOKEN>

אסימונים נוצרים בלוח הבקרה של Quickchat תחת אפליקציות חיצוניות > API. כל אסימון הוא JWT שמכיל scenario_id, ולכן אין צורך בכותרת מזהה נוספת.

• תוקף אסימון: 52 שבועות מהיצירה
• אפשר לבטל אסימונים בכל עת מלוח הבקרה
• כל אסימון מוגבל לסוכן AI אחד (תרחיש)
• יצירת אסימונים דורשת תוכנית Business ומעלה; בתוכניות נמוכות יותר האפשרות מושבתת ונקודת הקצה מחזירה 402 Payment Required

Note

נקודת הקצה לצ’אט בזמן אמת (POST https://app.quickchat.ai/chat) מקבלת אותו Bearer token כמו יתר ה-API, אך נמצאת מחוץ לנתיב הבסיס /v1/api/ ודורשת scenario_id בגוף הבקשה. ראו צ’אט למלוא התיעוד.

היקפי הרשאה של אסימונים

אסימוני API נוצרים באחד משני היקפים:

היקף	רמת גישה	תיאור
read_all	קריאה בלבד	קריאת כל המשאבים, ללא יצירה, עדכון או מחיקה
write_all	קריאה וכתיבה	גישה מלאה לכל נקודות הקצה, כולל כתיבה

• ההיקף נקבע ביצירת האסימון בלוח הבקרה תחת אפליקציות חיצוניות > API
• write_all כולל אוטומטית את כל הרשאות read_all
• שימוש באסימון read_all בנקודת כתיבה מחזיר 403 עם "Insufficient token scope. Required: write_all"

Tip

השתמשו ב-read_all לניטור, ניתוח ותוספים לקריאה בלבד. השתמשו ב-write_all רק כשהתוסף צריך ליצור או לשנות משאבים.

ההרשאות הנדרשות לפי קבוצת נקודות קצה:

קבוצה	פעולות קריאה	פעולות כתיבה
הגדרות צ’אטבוט	read_all	write_all
הגדרות מאגר ידע	read_all	write_all
מאמרים	read_all	write_all
כתובות מאמר לפי שפה	read_all	write_all
תגיות	read_all	אין
העלאת קבצים	אין	write_all
ייבוא תוכן חיצוני	אין	write_all
מאגר הידע של Intercom	read_all	write_all
הגדרות ווידג’ט	read_all	write_all
שיחות	read_all	אין
מטא-נתוני שיחה	read_all	write_all
הגדרות העברה	read_all	write_all
דירוג שיחה	read_all	write_all
פעולות AI	read_all	write_all

כתובת בסיס

קבוצת נקודות קצה	כתובת בסיס
מאגר ידע, פעולות AI, העלאת קבצים, ייבוא, הגדרות צ’אטבוט, ווידג’ט, העברה, דירוג שיחה	https://app.quickchat.ai/v1/api/
שיחות	https://app.quickchat.ai/v1/api_core/
צ’אט בזמן אמת	https://app.quickchat.ai/chat

מגבלות קצב

מגבלות הקצב חלות לכל אסימון ולכל נקודת קצה.

סוג	מגבלה	חל על
READ	120 בקשות לדקה	GET ופעולות רשימה
WRITE	60 בקשות לדקה	POST, PATCH, PUT, DELETE
HEAVY	20 בקשות לדקה	העלאות קבצים, ייבוא ואיסוף תוכן

בחריגה מהמגבלה, ה-API מחזיר HTTP 429 Too Many Requests.

Webhooks

Quickchat AI אינה שולחת webhooks יוצאים. אי אפשר להירשם לאירוע ולקבל מאיתנו POST כשמגיעה הודעה, כששיחה מועברת לנציג או כששיחה נסגרת.

החלופות הזמינות מיועדות לצרכים שונים:

• פעולות AI קוראות ל-API שלכם במהלך שיחה. לפעולות API מצבי ה־AI מחליט, לפני התשובה הראשונה וכאשר המטא־נתונים תואמים. המצבים האוטומטיים מנסים קריאה פעם אחת לשיחה בתנאים המתועדים; אינם מנוי לכל הודעה או העברה. השתמשו בהם לרישום ליד או לעדכון המערכת כשהנתונים הדרושים זמינים.
• Google Sheets מוסיף שורה כשהפעולה שלו פועלת. הוא אינו מתעד אוטומטית כל הודעה או העברה.
• בדיקה מחזורית של Conversations API מחזירה שיחות שמורות ואירועים, כולל הודעות וסימוני העברה שתועדו. הקפידו על עימוד ועל מגבלת READ. בדיקה מחזורית מוסיפה השהיה; השוואת מצב בין בדיקות עלולה לפספס שינויים באמצע. אל תניחו שהיא מספקת היסטוריה מלאה של כל העברה או שינוי שיוך.

גישה ל-API דורשת תוכנית Business; ראו תוכניות ומגבלות.

עימוד

נקודות רשימה תומכות בעימוד באמצעות פרמטרי שאילתה:

פרמטר	תיאור
limit מספר שלם	מספר פריטים לדף
offset מספר שלם	מספר פריטים לדילוג

תגובות עם עימוד משתמשות במבנה הבא:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

טיפול בשגיאות

כל השגיאות מוחזרות כ-JSON בפורמט הבא:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

סטטוס	קוד	תיאור
400	BAD_REQUEST	קלט לא תקין או שדות חובה חסרים
401	PERMISSION_DENIED	אסימון לא תקין, שפג או שבוטל
402	PAYMENT_REQUIRED	נדרש מנוי פעיל
403	PERMISSION_DENIED	לאסימון חסרה ההרשאה הדרושה
404	NOT_FOUND	המשאב לא נמצא
409	CONFLICT	פעולה מתנגשת, למשל שינוי מקביל
422	VALIDATION_ERROR	גוף הבקשה נכשל באימות הסכימה
429	TOO_MANY_REQUESTS	חריגה ממגבלת הקצב
500	UNKNOWN	שגיאת שרת פנימית
503	SERVICE_UNAVAILABLE	אי-זמינות זמנית

---