צ'אט

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

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

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

צ’אט

נקודת הצ’אט בזמן אמת שולחת הודעת מבקר לסוכן ומחזירה תשובת AI בבקשה אחת. היא מיועדת לבניית ממשק צ’אט מותאם על Quickchat AI.

היא שונה משאר נקודות הקצה בשני היבטים: נמצאת ב-app.quickchat.ai/chat, מחוץ לנתיבי הבסיס /v1/api/ ו-/v1/api_core/, וקוראת scenario_id מגוף הבקשה ולא מהאסימון. היא משתמשת באותו אימות Bearer token כמו יתר ה-API.

Note

שלחו כל בקשה אל https://app.quickchat.ai/chat. ה-scenario_id בגוף חייב להתאים לסוכן שאליו קשור ה-Bearer token.

שליחת הודעה

POST https://app.quickchat.ai/chat

גוף הבקשה

פרמטר	תיאור
scenario_id מחרוזת, חובה	מזהה הסוכן. חייב להתאים ל-scenario_id של ה-Bearer token
text מחרוזת, חובה	הודעת המשתמש
conv_id מחרוזת	מזהה שיחה. השמיטו בבקשה הראשונה ליצירת שיחה, ואז העבירו את conv_id שהוחזר בבקשות הבאות להמשך
client_metadata אובייקט	זוגות מפתח-ערך מותאמים (מומלץ עד 5 מפתחות) שמצורפים לכל הודעה. מוצגים כעמודות נתונים בייצוא שיחות מתיבת הדואר הנכנס

בקשה ללא conv_id מתחילה שיחה חדשה ומחזירה מזהה conv_id. שמרו את conv_id ושלחו בבקשות הבאות כדי לשמר הקשר לאורך כמה אינטראקציות.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

תגובה 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

שדה	תיאור
conv_id מחרוזת	מזהה השיחה. מוחזר תמיד. שלחו שוב בשדה הגוף conv_id כדי להמשיך
reply מחרוזת	תשובת הסוכן. עשויה לכלול HTML כמו מעברי שורה <br>
ord_number מספר שלם	מספר ההודעה הרציף בשיחה
src מספר שלם	סימון מקור פנימי. לקוחות API יכולים להתעלם

להמשך שיחה קיימת, שלחו את conv_id שקיבלתם:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

מטא-נתוני לקוח

נקודת הצ’אט מקבלת client_metadata אופציונלי: מאפיינים מותאמים המשויכים לכל הודעה חדשה ומוצגים כעמודות בייצוא השיחות. אפשר לצרף אותם גם דרך הווידג’ט. מומלץ לשלוח עד 5 מפתחות בכל פעם, למשל {"userId": 12, "website": "mywebsite.com"}. זו המלצה, לא מגבלה שנאכפת ב-API.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

סינון מאגר ידע לפי תגיות

אפשר להוסיף תגיות למאמרי מאגר ידע ולהגביל את המאמרים שה-AI משתמש בהם, כך שיענה רק מתוך תת-קבוצה. הסינון נתמך כרגע רק דרך ה-API.

לסינון לפי תג, הוסיפו kb_topic ל-client_metadata. המפתח kb_topic חייב להופיע בכל בקשה בשיחה, כולל הראשונה. הערך יכול להשתנות בין בקשות, אך המפתח עצמו חייב להישאר לאורך כל השיחה כדי שהסינון יחול.

בדוגמה הבאה כל מאמר עם התג your-topic, או ללא תג כלל, נכלל במאגר המועמדים לתשובה.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

שגיאות

נקודת הצ’אט מחזירה הודעת שגיאה בטקסט רגיל עם קוד HTTP מתאים.

סטטוס	תיאור	פעולה
400	חסר scenario_id או לא סופקו פרטי גישה	כללו scenario_id בגוף וכותרת תקינה Authorization: Bearer <API_TOKEN>
400	conv_id לא תקין (Conversation conv_id <id> is not valid.)	השמיטו conv_id להתחלת שיחה או השתמשו ב-conv_id שהוחזר קודם
401	פרטי גישה לא תקינים (Unauthorized.)	בדקו שה-Bearer token או מפתח ה-API תקפים ל-scenario_id הזה
404	scenario_id לא מוכר (No implementation found for scenario_id <id>)	ודאו את scenario_id ושהאסימון קשור אליו
500	שגיאת שרת פנימית	בעיה בצד שלנו. פנו לתמיכה
503	השירות לא זמין	עומס זמני או תחזוקה. אם הבעיה נמשכת, פנו לתמיכה