מטא-נתונים של תמליל הצ'אט

במאמר הזה מוסבר על הסכימה של רשומת המטא-נתונים של תמליל הצ'אט. זהו קובץ ה-JSON שנוצר על ידי Contact Center AI Platform (פלטפורמת CCAI) לתמליל צ'אט שהושלם. רשומת המטא-נתונים של תמליל הצ'אט נוצרת על ידי ייצוא JSON של היסטוריית הצ'אט, ויכולה להישלח באמצעות העלאות של תמלילי צ'אט ל-CRM וקבצים של תמלילי צ'אט באחסון חיצוני, בהתאם להגדרות של המופע. אפשר להשתמש בסכימה הזו כדי לנתח JSON של תמליל, לאמת מטענים ייעודיים (payloads) שהתקבלו או למפות הודעות תמליל למערכות במורד הזרם.

הרמה הבסיסית (root) של הסכימה

רשומת המטא-נתונים של תמליל הצ'אט היא אובייקט JSON יחיד שמייצג ארטיפקט אחד של תמליל הצ'אט. השדות ברמת הבסיס מזהים את התקשורת, את גרסת הפורמט של התמליל ואת קבוצת הרשומות של התמליל לפי הסדר.

מזהי תקשורת comm_type ו-comm_id

ביחד, comm_type ו-comm_id מזהים את התקשורת שהתמליל הזה מייצג.

• ‫comm_type הוא המזהה של סוג התקשורת. הערך הוא בדרך כלל chat. יכול להיות שזה call לשיחה קולית שכוללת תוכן משולב של תמליל SMS.

• ‫comm_id הוא המזהה של הצ'אט או השיחה שמיוצגים בתמליל.

גרסת הפורמט transcript_version

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

דיסקרימינטור של רשומה – entries[].type ו-entries[].body.type

כל פריט ב-entries מייצג הודעה או אירוע בתמליל. השדה type ברמת הכניסה משקף את סוג גוף ההודעה. אובייקט body המקונן מכיל את מטען הייעודי (payload) שהמבנה שלו משתנה בהתאם לסוג – לדוגמה, text,‏ markdown,‏ photo,‏ noti או action.

סכימת מטא-נתונים של תמליל הצ'אט

בסכמה הזו מתואר מבנה הנתונים של תמלילי צ'אטים. בקטעים הבאים מתוארים רכיבי הליבה.

מידע ליבה בתמליל

המאפיינים הבאים מספקים את המידע הבסיסי על התמליל עצמו:

• ‫comm_type (string): סוג התקשורת שהתמליל מייצג. ערכים אפשריים: chat, call. הערך call מציין שיחת טלפון עם תוכן משולב של תמליל SMS.

• ‫comm_id (מספר שלם): מזהה ייחודי של התקשורת שמיוצגת בתמליל.

• ‫transcript_version (מחרוזת): הגרסה של פורמט ה-JSON של התמליל. הערך הנוכחי הוא "1.0". מידע על ניהול גרסאות והוצאה משימוש

• ‫assigned_at (string, date-time): חותמת הזמן שבה הצ'אט שויך.

• ‫timezone (מחרוזת): אזור הזמן של הקשר בתמליל, למשל "America/Los_Angeles".

רשומות בתמליל

• ‫entries (array): רשימה ממוינת של רשומות בתמליל. כל רשומה מייצגת הודעה, התראה או פעולה בשיחה.

  • ‫timestamp (מספר שלם): חותמת זמן של מערכת Unix בשניות, שבה המערכת יצרה את הרשומה.

  • ‫type (מחרוזת): סוג גוף ההודעה. הערך הזה זהה לערך של body.type. בקטע הגדרות מפורטים סוגי הגוף הנתמכים.

  • ‫body (object): מטען ייעודי (payload) של רשומה. הצורה שלו תלויה בערך של type / body.type.

  • ‫role (string): התפקיד של המשתתף או של רכיב המערכת שיצר את הרשומה. ערכים אפשריים: end_user, ‏ agent, ‏ manager, ‏ virtual_agent, ‏ external_agent, ‏ task_virtual_agent, ‏ system.

  • ‫user_data (object): מטא-נתונים של השולח. עבור רשומות של agent, ‏manager, ‏virtual_agent, ‏external_agent ו-task_virtual_agent, האובייקט הזה מכיל את נתוני התצוגה של השולח. האובייקט הזה ריק עבור רשומות של end_user ו-system.

    • ‫name (מחרוזת; מופיע רק אם יש מטא-נתונים של השולח): השם המוצג של השולח.

    • ‫id (מספר שלם; מופיע רק כשמטא-נתונים של השולח זמינים): מזהה של השולח.

    • ‫avatar_url (מחרוזת, uri; קיים רק כשמטא-נתונים של השולח זמינים): כתובת ה-URL של תמונת הדמות של השולח.

גוף הודעת הטקסט

• ‫text (object): גוף ההודעה בטקסט פשוט.

  • ‫type (string): Always text.

  • ‫content (מחרוזת): טקסט ההודעה.

  • ‫lang (מחרוזת; מופיע רק כשמטא-נתונים של שפה זמינים): קוד השפה שמשויך להודעה.

• ‫text_template (אובייקט): גוף ההודעה עם תבנית.

  • ‫type (string): Always text_template.

  • ‫content (מחרוזת): טקסט התבנית.

• ‫markdown (object): גוף ההודעה בפורמט Markdown.

  • ‫type (string): Always markdown.

  • ‫content (מחרוזת): תוכן ב-Markdown.

  • ‫lang (מחרוזת; מופיע רק כשמטא-נתונים של שפה זמינים): קוד השפה שמשויך להודעה.

• ‫markdown_template (object): גוף ההודעה ב-Markdown עם תבנית.

  • ‫type (string): Always markdown_template.

  • ‫content (מחרוזת): תוכן תבנית Markdown.

גוף ההודעה של קבצים וקבצי מדיה

• ‫photo (אובייקט): גוף ההודעה עם התמונה או צילום המסך.

  • ‫type (string): Always photo.

  • ‫media_id (מספר שלם): מזהה של מדיה מסוג תמונה שמאוחסנת.

• ‫video (אובייקט): גוף הודעת וידאו.

  • ‫type (string): Always video.

  • ‫media_id (מספר שלם; קיים כשהמערכת מאחסנת את הסרטון כמדיה של פלטפורמת CCAI): מזהה של מדיה של סרטון מאוחסן.

  • ‫title (מחרוזת; מופיע כשסרטון מוטמע מייצג את הסרטון): שם הסרטון.

  • ‫video (אובייקט; מופיע כשסרטון מוטמע מייצג את הסרטון): פרטי הסרטון.

    • ‫url (מחרוזת, URI): כתובת ה-URL של הסרטון.

    • ‫text (מחרוזת): טקסט חלופי או כתובת URL חלופית לסרטון.

• ‫image (אובייקט): גוף הודעת התמונה.

  • ‫type (string): Always image.

  • ‫title (מחרוזת; מוצג אם השולח של ההודעה סיפק אותו): שם התמונה.

  • ‫image (object): פרטי התמונה.

    • ‫url (string, uri): כתובת ה-URL של התמונה.

    • ‫text (string): טקסט חלופי או כתובת URL חלופית לתמונה.

• ‫document (אובייקט): גוף ההודעה במסמך.

  • ‫type (string): Always document.

  • ‫media_id (מספר שלם; מופיע כשהמערכת מאחסנת את המסמך כמדיה של פלטפורמת CCAI): מזהה של מדיה של מסמך מאוחסן.

  • ‫title (מחרוזת; מופיע כשמסמך מוטמע מייצג את המסמך): שם המסמך.

  • ‫document (אובייקט; מופיע כאשר אובייקט של מסמך מוטמע מייצג את המסמך): פרטי המסמך.

    • ‫url (string, uri): כתובת ה-URL של המסמך.

    • ‫text (מחרוזת): טקסט חלופי או כתובת URL חלופית למסמך.

• ‫audio (object): גוף ההודעה הקולית.

  • ‫type (string): Always audio.

  • ‫media_id (מספר שלם; מופיע כשהמערכת מאחסנת את האודיו כמדיה של CCAI Platform): מזהה של מדיה האודיו המאוחסנת.

  • ‫title (מחרוזת; קיים כשקובץ אודיו מוטמע מייצג את קובץ האודיו): שם קובץ האודיו.

  • ‫audio (object; present when an embedded audio object represents the audio file): פרטי אודיו.

    • ‫url (מחרוזת, uri): כתובת ה-URL של קובץ האודיו.

    • ‫text (string): טקסט חלופי או כתובת URL חלופית לקובץ האודיו.

גוף ההודעה האינטראקטיבי

• ‫inline_button (אובייקט): גוף ההודעה של כפתור מוטבע.

  • ‫type (string): Always inline_button.

  • ‫title (מחרוזת): הכותרת שתוצג מעל הלחצנים.

  • ‫buttons (array): רשימה של הגדרות כפתורים.

    • ‫title (מחרוזת): תווית הכפתור.

    • ‫action (string): הפעולה שמשויכת ללחצן.

    • link (מחרוזת, uri; קיים רק בתשובות מהירות בסגנון קישור): כתובת ה-URL שמשויכת ללחצן.

• ‫sticky_button (אובייקט): גוף ההודעה של לחצן במיקום קבוע.

  • ‫type (string): Always sticky_button.

  • ‫title (מחרוזת): הכותרת שתוצג מעל הלחצנים.

  • ‫buttons (array): רשימה של הגדרות כפתורים.

    • ‫title (מחרוזת): תווית הכפתור.

    • ‫action (string): הפעולה שמשויכת ללחצן.

    • link (מחרוזת, uri; קיים רק בתשובות מהירות בסגנון קישור): כתובת ה-URL שמשויכת ללחצן.

• ‫content_card (אובייקט): גוף ההודעה של כרטיס התוכן.

  • ‫type (string): Always content_card.

  • cards (array): רשימה של כרטיסי תוכן.

    • ‫title (string): כותרת הכרטיס.

    • ‫body (מחרוזת; מוצג רק כשמגדירים טקסט בגוף הכרטיס): טקסט בגוף הכרטיס.

• ‫form_complete (object): גוף ההודעה על השלמת הטופס שהלקוח שולח כשלקוח משלים טופס, לא מצליח להשלים אותו או מבטל אותו.

  • ‫type (string): Always form_complete.

  • ‫signature (מחרוזת; מופיע רק כשאירוע ההשלמה מכיל חתימה): חתימה של מטען הייעודי (payload) של השלמת הטופס.

  • ‫data (object): פרטים על מילוי הטופס.

    • ‫status (מחרוזת): סטטוס ההשלמה. ערכים אפשריים: success, ‏ error, ‏ cancelled.

    • ‫smart_action_id (מספר שלם): מזהה הפעולה החכמה שמשויכת לטופס.

    • timestamp (מחרוזת, תאריך ושעה): חותמת הזמן שבה התרחש אירוע השלמת הטופס. הערך הזה שונה מהערך ברמת הכניסה timestamp, שהוא חותמת זמן של מערכת Unix בשניות.

    • ‫details (אובייקט; מופיע רק אם המטען הייעודי (payload) מספק פרטים נוספים על השלמת הפעולה): פרטים נוספים על הסטטוס.

      • ‫error_code (מחרוזת; מופיע רק בשגיאות עם קוד): קוד השגיאה שמשויך לתוצאת ההשלמה.

      • ‫message (מחרוזת): פרטי סטטוס שקריאים לאנשים.

גופי הודעות שנוצרו על ידי השרת והודעות שמועברות דרך השרת

• ‫server_message (אובייקט): גוף ההודעה שנוצר על ידי השרת. התמליל כולל server_message רק אם הפעלתם בחשבון את האפשרות 'תוכן תמליל של נציג וירטואלי למשימות'. אחרת, התמליל לא כולל את הרשומות האלה. משתמשים באובייקט הזה כשהתמליל מתייחס להודעה שמאוחסנת בצד השרת.

  • ‫type (string): Always server_message.

  • ‫message_id (מספר שלם): מזהה של הודעת השרת המאוחסנת.

  • ‫visibility (מחרוזת או null): הגדרת החשיפה של הודעת השרת המאוחסנת.

• ‫passthrough (object): מטען ייעודי (payload) בהתאמה אישית שהמערכת מעבירה דרך פלטפורמת CCAI לשילוב של סוכן וירטואלי או CCaaS. השילוב מגדיר את content שלו, שלא נכלל בסכימה של CCAI Platform. צריך להתייחס אליו כאל אטום.

  • ‫type (string): Always passthrough.

  • ‫content (מחרוזת או אובייקט): מטען ייעודי (payload) שמוגדר על ידי השילוב. המבנה שלה משתנה בהתאם לשילוב, ופלטפורמת CCAI לא מפרשת אותו.

גוף ההודעה עם הפעולה

• ‫action (אובייקט): פעולה שרצף פעולות של נציג וירטואלי או צ'אטבוט מבקש. השדה action קובע את מבנה מטען הייעודי (payload) של הפעולה.

  • ‫type (string): Always action.

  • ‫action (string): סוג הפעולה. הערכים האפשריים כוללים escalation, deflection וגם end.

  • ‫escalation_reason (מחרוזת; מופיע רק אם הערך של action הוא escalation): הסיבה להעברת השיחה לטיפול ברמה גבוהה יותר.

  • ‫menu_id (מספר שלם; מופיע רק אם הערך של action הוא escalation): מזהה התפריט שאליו צריך להעביר את השיחה.

  • ‫language (string; present only when action is escalation): קוד השפה של תור היעד.

  • ‫deflection_type (מחרוזת; מופיע רק אם הערך של action הוא deflection): סוג ההפניה המבוקשת.

  • ‫sip_parameters (אובייקט או null; קיים רק אם action הוא deflection): פרמטרים של SIP להעברה כחלק מההפניה.

גוף ההודעה לידיעה

• ‫noti (object): גוף ההודעה של ההתראה. ההתראות מתארות אירועים במערכת שהתרחשו במהלך הצ'אט.

  • ‫type (string): Always noti.

  • ‫event (מחרוזת): שם אירוע ההתראה.

  • ‫agent (אובייקט; קיים רק באירועים שמשויכים לנציג אנושי): הנציג שמשויך לאירוע.

    • ‫id (מספר שלם): מזהה הסוכן.

    • ‫email (מחרוזת, אימייל): כתובת האימייל של הסוכן.

    • ‫name (מחרוזת): השם המוצג של הסוכן.

  • ‫from_agent (אובייקט; קיים רק באירועי העברה עם סוכן מקור): סוכן המקור של האירוע.

    • ‫id (מספר שלם): מזהה הסוכן.

    • ‫email (מחרוזת, אימייל): כתובת האימייל של הסוכן.

    • ‫name (מחרוזת): השם המוצג של הסוכן.

  • ‫to_agent (אובייקט; קיים רק באירועים של העברה או הסלמה עם סוכן אנושי כיעד): סוכן אנושי כיעד של האירוע.

    • ‫id (מספר שלם): מזהה הסוכן.

    • ‫email (מחרוזת, אימייל): כתובת האימייל של הסוכן.

    • ‫name (מחרוזת): השם המוצג של הסוכן.

  • from_virtual_agent (אובייקט; מוצג רק לאירועי העברה לטיפול ברמה גבוהה יותר מנציג וירטואלי): הסוכן הווירטואלי המקורי של האירוע.

    • ‫id (מספר שלם): מזהה של נציג וירטואלי.

    • ‫name (string): השם המוצג של הסוכן הווירטואלי.

    • ‫avatar_url (string, uri, or null): כתובת ה-URL של תמונת האווטאר של הסוכן הווירטואלי.

  • ‫to_virtual_agent (אובייקט; קיים רק באירועי העברה לנציג וירטואלי): הנציג הווירטואלי שאליו מועבר האירוע.

    • ‫id (מספר שלם): מזהה של נציג וירטואלי.

    • ‫name (string): השם המוצג של הסוכן הווירטואלי.

    • ‫avatar_url (string, uri, or null): כתובת ה-URL של תמונת האווטאר של הסוכן הווירטואלי.

  • ‫target (מחרוזת; מופיע רק באירועי העברה): סוג היעד של ההעברה. הערכים האפשריים הם menu ו-agent.

  • ‫status (מחרוזת; מופיע רק באירועים שכוללים סטטוס של צ'אט): סטטוס הצ'אט שמשויך לאירוע.

  • ‫timeout (boolean; present only for timeout-related events): Whether a timeout caused the event.

  • ‫memberIdentity (מחרוזת; מופיע רק באירועים של הצטרפות או עזיבה של משתתפים): זהות המשתתף.

  • ‫memberName (string; present only for participant join or leave events): השם המוצג של המשתתף.

  • ‫name (מחרוזת; מופיע רק באירועים מסוג virtual-agent או task-va): השם המוצג שמשויך לאירוע.

  • ‫reason (מחרוזת; מופיע רק באירועי השלמת task-va): הסיבה לסיום הסשן של task-va.

  • ‫escalation_reason (מחרוזת; מופיע רק באירועי העברה לטיפול ברמה גבוהה יותר): הסיבה להעברה לטיפול ברמה גבוהה יותר.

  • ‫deflection (אובייקט; מופיע רק באירועי הפניה): פרטי ההפניה.

  • ‫detail (אובייקט; מופיע רק באירועים של התראות מותאמות אישית): פרטים של אירוע מותאם אישית.

    • ‫key (מחרוזת): מפתח של אירוע מותאם אישית.

    • ‫data (אובייקט): מטען ייעודי (payload) של אירוע בהתאמה אישית.

שמות של אירועי התראות

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

בקשות לפעולות חכמות

• verificationRequested

• photoRequested

• videoRequested

• screenshotRequested

• textRequested

• cobrowseRequestedFromAgent

תוצאות של פעולות חכמות

• הושלם: photoFinished, videoFinished, screenshotFinished, textFinished

• בוטל: photoCanceled, videoCanceled, screenshotCanceled, textCanceled, cobrowseCanceled

• נכשל: photoFailed, ‏ videoFailed, ‏ screenshotFailed, ‏ textFailed, ‏ verificationFailed

אימות

• endUserVerified

גלישה משותפת

• cobrowseRequestedFromEndUser

• cobrowseCodeGenerated

• cobrowseStarted

• cobrowseEnded

• cobrowseFailed

Forms

• formRequested

• formSent

• formCompleted

העברות

• transferStarted

• transferAccepted

• transferFailed

העברה לטיפול בנציג וירטואלי

• escalationStarted

• escalationAccepted

• escalationDeflected

• escalationFailed

נציג וירטואלי למשימות

• taskVaStarted

• taskVaFinished

חברות

• memberJoined

• memberLeft

מחזור החיים של סשן

• chatEnded

• chatEndedWithPostSession

• chatDismissed

• checkInRequired

• checkInTimedOut

• transcriptRequested

• transcriptUpdated

בהתאמה אישית

• custom

יכול להיות שיופיעו אירועים נוספים של התראות על תמלילי שיחות ברשומות שבהן הערך של comm_type הוא call. האירועים האלה משויכים לטיפול בתמלילים של שיחות או של Agent Assist, ולא למשפחות הרגילות של אירועים ב-Chat.

הגדרות

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

רשומה (אובייקט)

מייצג הודעה, התראה או פעולה אחת בתמליל. לכל רשומה יש timestamp של Unix-epoch,‏ type ברמה העליונה, אובייקט body שהסוג שלו תואם לצורה הזו, role של השולח ואובייקט user_data. כאן אפשר לראות את הרשימה המלאה של השדות.

user_data (object)

מתאר את השולח של רשומה בתמליל, אם יש מטא-נתונים של השולח. רשומות של סוכן, מנהל, סוכן וירטואלי, סוכן חיצוני וסוכן וירטואלי למשימות יכולות להכיל את הערכים name, id ו-avatar_url. רשומות של צרכנים ומערכות מכילות אובייקט ריק.

גוף ההודעה (אובייקט, oneOf)

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

תפקיד המשתתף (מחרוזת, enum)

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

ערכים מותרים

• ‫end_user – הצרכן.

• ‫agent – נציג תמיכה אנושי.

• manager – משתתף עם הרשאת ניהול.

• ‫virtual_agent – נציג וירטואלי.

• ‫external_agent – משתתף חיצוני שהוא סוכן.

• ‫task_virtual_agent – נציג וירטואלי לטיפול במשימות.

• ‫system – רשומה שנוצרה על ידי המערכת.

ניהול גרסאות והוצאה משימוש

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

גרסת הפורמט הנוכחית

• ‫transcript_version (string) – הערך הנוכחי: "1.0". השילובים צריכים לנתח את התמליל על סמך השדות שמופיעים במטען הייעודי (payload), ולא להיכשל אם בגרסאות עתידיות יתווספו שדות חדשים או סוגים חדשים של גוף ההודעה.

סוגים לא ידועים של גוף ההודעה

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

שדות שיצאו משימוש

במסמך הזה לא מפורטים שדות שהוצאו משימוש ברשומה של המטא-נתונים של תמליל הצ'אט.