Disposition codes API

ה-API של קודי הסטטוס מאפשר לשילוב שלכם לבצע את הפעולות הבאות:

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

• עדכון קודי הטיפול או ההערות (או שניהם) לשיחה או לצ'אט שהסתיימו.

אימות וכתובת URL בסיסית

כל נקודות הקצה במסמך הזה משתמשות באימות רגיל של אסימון API באמצעות אסימון משתמש API (אסימון bearer).

כתובת אתר הבסיס: https://SUBDOMAIN.REGION_CODE.ccaiplatform.com

קבלת רשימת קודי סיום השיחה

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

לפי מכונה

הפונקציה מחזירה את העץ המלא של קודי הסיווג של המופע, כולל כל קודי הסיווג הרב-רמתיים.

דוגמה לבקשה

הבקשה הבאה מחזירה את הרשימה המלאה של קודי הטיפול:

GET /api/v1/disposition_codes
Authorization: Bearer {token}
Content-Type: application/json

דוגמה לתשובה

בדוגמה הבאה לתגובה מוצגת הרשימה המלאה של קודי הסיווג:

{
  "disposition_codes": [
    {
      "id": 1,
      "name": "Issue Resolved",
      "full_path": "/Support/Issue Resolved",
      "children": []
    },
    {
      "id": 2,
      "name": "Escalated",
      "full_path": "/Support/Escalated",
      "children": [
        {
          "id": 3,
          "name": "Tier 2",
          "full_path": "/Support/Escalated/Tier 2",
          "children": []
        }
      ]
    }
  ]
}

לפי תור

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

דוגמה לבקשה

הבקשה הבאה מקבלת קודי סיום שיחה לתור:

GET /api/v1/disposition_codes?queue_id=QUEUE_ID
Authorization: Bearer TOKEN
Content-Type: application/json

פרמטרים של שאילתה

פרמטר	סוג	חובה	תיאור
queue_id	מספר שלם	כן	המזהה של התור שרוצים לקבל את קודי הסטטוס שלו.

לפי סשן

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

דוגמה לבקשה

הבקשה הבאה מקבלת קודי סיום שיחה עבור סשן:

GET /api/v1/disposition_codes?session_id=SESSION_ID
Authorization: Bearer TOKEN
Content-Type: application/json

פרמטרים של שאילתה

פרמטר	סוג	חובה	תיאור
session_id	מספר שלם	כן	מזהה הסשן.

עדכון קוד הסטטוס וההערות

שליחת קוד סיום או הערות (או שניהם) מעודכנים לגבי שיחה או צ'אט שהסתיימו. כך נוצרת רשומה חדשה של סטטוס הטיפול ונוספת הערה ב-CRM. הוא לא עורך את הרשומה המקורית ב-CRM.

דוגמה לבקשה

הבקשה הבאה מעדכנת את קוד הסיום או את ההערות של שיחה:

POST /api/v1/sessions/SESSION_ID/disposition
Authorization: Bearer TOKEN
Content-Type: application/json

פרמטרים של נתיבים

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

דוגמה לגוף הבקשה

בדוגמה הבאה מוצג גוף בקשה:

{
  "disposition_code": {
    "id": 5,
    "full_path": "/Support/Verification/Pending Documents"
  },
  "notes": "Customer must upload documents via portal."
}

פרמטרים של גוף הבקשה

פרמטר	סוג	חובה	תיאור
disposition_code	אובייקט	מותנה	קוד הסיווג המעודכן. צריך לציין לפחות אחד מהמאפיינים disposition_code או notes.
disposition_code.id	מספר שלם	כן (אם מצוין disposition_code)	המזהה של קוד הסיווג.
disposition_code.full_path	מחרוזת	כן (אם מצוין disposition_code)	הנתיב ההיררכי המלא של קוד הסטטוס, לדוגמה: /Support/Verification/Pending Documents. משמש לאימות מול עץ ההחלטות של הסשן.
notes	מחרוזת	לא	הערות הסוכן המעודכנות. אפשר לעיין בטבלה בנושא התנהגות של הערות.

אופן הפעולה של ההערות

ערך	התנהגות
הצגה עם טקסט, לדוגמה, "notes": "Updated notes"	ההערה הקיימת תוחלף בטקסט החדש.
הערך מוצג כמחרוזת ריקה ("notes": "")	מחיקה מפורשת של ההערה הקיימת. ההערה לא תופיע יותר בקובץ המטא-נתונים של הסשן. ההיסטוריה של ה-CRM שומרת רשומות קודמות.
הושמט (השדה לא מופיע בבקשה)	ההערה הקיימת לא משתנה.

תוצאת שיחה מסוג 'לא להתקשר' (DNC)

כדי לשלוח סטטוס של שיחה שלא רוצים לקבל ממנה שיחות, משתמשים ב-disposition_code.id: -1. הערך הזה מתקבל רק אם התכונה 'לא להתקשר' מופעלת במופע והוגדרה תוצאה של 'לא להתקשר'. אחרת, ה-API מחזיר 422 Unprocessable Entity עם ההודעה: "ההגדרה 'לא להתקשר' לא מופעלת בדייר הזה".

ייחוס לסוכן

ה-API לא כולל זהות של סוכן. המערכת משייכת את הסטטוס של הלידים לאפשרויות הבאות, לפי סדר העדיפות:

1. הסוכן ששלח במקור את הסטטוס של הסשן הזה.

2. אם אין תוצאה מקורית, הסוכן שהשתתף בשיחה או בצ'אט הכי לאחרונה.

אם אף אחד מהם לא קיים, ה-API מחזיר 422 Unprocessable Entity.

אימות

הרשימה הבאה מתארת את כללי האימות:

• השיחה או הצ'אט בסשן צריכים להסתיים. ניסיון לעדכן את הסטטוס של שיחה פעילה מחזיר 422 Unprocessable Entity.

• הפרמטרים disposition_code.id ו-disposition_code.full_path עוברים אימות מול עץ ההפניות של הסשן (על סמך התור שהסשן הופנה אליו לאחרונה).

• הגדרת האדמין allow_disposition_edit היא אמצעי בקרה בממשק המשתמש בלבד. ה-API הציבורי תמיד יכול לעדכן נתוני סטטוס, ללא קשר להגדרה הזו.

דוגמה לתשובה

בדוגמה הבאה מוצגת תגובה לבקשה שבוצעה בהצלחה:

{
  "session_id": 12345,
  "disposition": {
    "id": 5,
    "name": "Verification Pending",
    "full_path": "/Support/Verification/Pending Documents",
    "notes": "Customer must upload documents via portal.",
    "submitted_at": "2026-03-13T10:15:01Z"
  }
}

הערה: השרת מחלץ את הערך של השדה name מעץ ההחלטות על סמך הערכים שצוינו בשדות id ו-full_path. הוא מוחזר בתגובה לנוחיותכם.

מטא-נתונים של סשן

כשמעדכנים סטטוס באמצעות ה-API הזה, מתרחשים הדברים הבאים:

• אחסון חיצוני: קובץ המטא-נתונים של הסשן נוצר מחדש ומחליף את קובץ המטא-נתונים הקיים.

• CRM: נוצרת הערה חדשה, והיסטוריית השינויים נשמרת.

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

בקטע הזה מתואר טיפול בשגיאות.

קודי סטטוס נפוצים

סטטוס	תנאי	הודעה לדוגמה
400 Bad Request	חסרים שדות חובה (disposition_code ו-notes), או שהפורמט לא תקין.	"צריך לציין לפחות אחד מהשדות disposition_code או notes".
401 Unauthorized	טוקן ה-API לא תקין או חסר.	‫"Unauthorized" (לא מורשה)
403 Forbidden	למשתמש ב-API אין גישה לסשן או לדייר שצוינו.	"Forbidden" (אסור)
404 Not Found	הסשן לא נמצא או שהוא לא קיים.	"הסשן לא נמצא".
422 Unprocessable Entity	כשלים שונים באימות. אפשר לעיין בטבלה 422 Unprocessable entity scenarios.	אפשר לעיין בטבלה 422 Unprocessable entity scenarios.

תרחישים של שגיאה ‎422 Unprocessable entity

תרחיש	הודעת השגיאה
השיחה או הצ'אט עדיין פעילים	"הסשן לא הסתיים. אפשר לעדכן את הסטטוס רק לגבי סשנים שהסתיימו".
לא נמצא מזהה קוד הסיווג בעץ של הסשן	"קוד הסטטוס לא תקין לתור של הסשן הזה".
הוגשה בקשה להוספת מספר לרשימת ה-DNC, אבל התכונה לא מופעלת	"ההגדרה 'תוצאת שיחה: לא להשאיר הודעה' לא מופעלת בדייר הזה".
לא ניתן לזהות משתתף שהוא סוכן לצורך שיוך	"לא ניתן לקבוע את הסוכן לצורך שיוך של תוצאת השיחה".

דוגמה לתשובה

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

{
  "error": {
    "code": "session_not_ended",
    "message": "Session has not ended. Disposition can only be updated for completed sessions.",
    "details": {
      "session_id": 12345
    }
  }
}

תהליך שילוב אופייני

זהו תהליך שילוב אופייני:

1. מקבלים קודי סיום שיחה לתור או לסשן הרלוונטיים:

   • GET /api/v1/disposition_codes?session_id=SESSION_ID

2. מציגים את עץ ההחלטות למשתמש או למערכת אוטומטית לבחירה.

3. שולחים את הסטטוס המעודכן:

   • POST /api/v1/sessions/SESSION_ID/disposition

   • צריך לכלול את קוד הטיפול שנבחר, עם התווים id ו-full_path, וכל הערה.

4. טיפול בתשובה:

   • בסטטוס 200 OK: הסטטוס עודכן. רשומות ה-CRM מתעדכנות באופן אוטומטי.

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

התנהגות של מערכת CRM

כששולחים סטטוס באמצעות ה-API הזה, קורים הדברים הבאים:

• נוצרת הערה חדשה במערכת ה-CRM המקושרת, כמו Salesforce,‏ ServiceNow,‏ Zendesk,‏ Dynamics או HubSpot. ההערה המקורית לא משתנה.

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

מגבלה

האינטראקציות עם שיחות ב-HubSpot כוללות מאפיין סקלרי hs_call_disposition שמוחלף (לא מצורף) בכל עדכון של סטטוס. ההיסטוריה המלאה נשמרת בהערות ב-HubSpot, אבל מאפיין האינטראקציה משקף רק את קוד הסיום העדכני ביותר.