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

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

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

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

מזהי תקשורת 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 (מחרוזת): סוג התקשורת שהתמליל מייצג. ערכים אפשריים: chat, ‏ call. הערך call מציין שיחת טלפון עם תוכן משולב של תמליל SMS.

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

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

• assigned_at (מחרוזת, תאריך-שעה): חותמת הזמן של הקצאת הצ'אט.

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

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

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

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

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

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

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

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

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

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

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

גוף הודעות ה-SMS

• ‫text (אובייקט): גוף הודעת ה-SMS בטקסט פשוט.

  • type (מחרוזת): תמיד text.

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

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

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

  • type (מחרוזת): תמיד text_template.

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

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

  • type (מחרוזת): תמיד markdown.

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

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

• ‫markdown_template (אובייקט): גוף ההודעה בפורמט Markdown.

  • type (מחרוזת): תמיד markdown_template.

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

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

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

  • type (מחרוזת): תמיד photo.

  • ‫media_id (מספר שלם): המזהה של קובץ המדיה של התמונה השמורה.

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

  • type (מחרוזת): תמיד video.

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

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

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

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

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

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

  • type (מחרוזת): תמיד image.

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

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

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

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

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

  • type (מחרוזת): תמיד document.

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

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

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

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

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

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

  • type (מחרוזת): תמיד audio.

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

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

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

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

    • ‫text (מחרוזת): טקסט חלופי או כתובת URL לגיבוי של קובץ האודיו.

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

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

  • type (מחרוזת): תמיד inline_button.

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

  • ‫buttons (מערך): רשימה של הגדרות לחצנים.

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

    • ‫action (מחרוזת): הפעולה שמשויכת לכפתור.

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

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

  • type (מחרוזת): תמיד sticky_button.

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

  • ‫buttons (מערך): רשימה של הגדרות לחצנים.

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

    • ‫action (מחרוזת): הפעולה שמשויכת לכפתור.

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

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

  • type (מחרוזת): תמיד content_card.

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

    • title (מחרוזת): כותרת הכרטיס.

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

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

  • type (מחרוזת): תמיד form_complete.

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

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

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

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

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

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

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

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

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

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

  • type (מחרוזת): תמיד server_message.

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

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

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

  • type (מחרוזת): תמיד passthrough.

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

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

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

  • type (מחרוזת): תמיד action.

  • ‫action (מחרוזת): סוג הפעולה. הערכים האפשריים כוללים את escalation,‏ deflection ו-end.

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

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

  • language (מחרוזת; מופיע רק כש-action הוא escalation): קוד השפה של תור היעד.

  • deflection_type (מחרוזת; מופיע רק כש-action הוא deflection): סוג ההסטה המבוקשת.

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

גוף ההודעה של ההתראות

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

  • type (מחרוזת): תמיד noti.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    • ‫avatar_url (מחרוזת, URI או null): כתובת ה-URL של תמונת הדמות של הנציג הווירטואלי.

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

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

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

    • ‫avatar_url (מחרוזת, URI או null): כתובת ה-URL של תמונת הדמות של הנציג הווירטואלי.

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

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

  • ‫timeout (בוליאני; מופיע רק באירועים שקשורים לזמן קצוב לתפוגה): אם האירוע נגרם בגלל זמן קצוב לתפוגה.

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

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

  • 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
• נכשל: photoFailed, videoFailed, screenshotFailed, textFailed, verificationFailed

אימות

• endUserVerified

גלישה משותפת

• cobrowseRequestedFromEndUser

• cobrowseCodeGenerated

• cobrowseStarted

• cobrowseEnded

• cobrowseFailed

Forms

• formRequested

• formSent

• formCompleted

העברות

• transferStarted

• transferAccepted

• transferFailed

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

• escalationStarted

• escalationAccepted

• escalationDeflected

• escalationFailed

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

• taskVaStarted

• taskVaFinished

חברות

• agentJoined

• memberJoined

• memberLeft

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

• chatEnded

• chatEndedWithPostSession

• chatDismissed

• chatReactivated

• checkInRequired

• checkInTimedOut

• transcriptRequested

• transcriptUpdated

בהתאמה אישית

• custom

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

הגדרות

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

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

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

user_data (אובייקט)

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

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

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

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

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

ערכים מותרים

• ‫end_user – הצרכן.

• ‫agent – נציג אנושי.

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

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

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

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

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

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

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

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

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

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

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

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

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