מדריך ל-Chat platform API

בדף הזה מוסבר איך להשתמש בנקודות קצה של צ'אט, כפי שמתואר במאמר נקודות קצה של API של פלטפורמת צ'אט.

הסברים על המונחים

לשם הבהרה, הנה כמה הגדרות שחשוב לזכור כשמשתמשים במסמך הזה.

  • לקוח: לקוח של Contact Center AI Platform (פלטפורמת CCAI) שמטמיע את ה-API של פלטפורמת הצ'אט בתוכנה שלו.

  • צרכן: התוכנה ששולחת בקשות ל-API של פלטפורמת הצ'אט.

  • משתמש קצה: המשתמש בתוכנה של הלקוח שמנסה לנהל צ'אט עם נציג.

אימות webhook

ה-API של פלטפורמת הצ'אט מעביר אירועים שמתרחשים במהלך הצ'אט לצרכן על ידי שליחת בקשות webhook לשרת של הצרכן. המטען הייעודי (Payload) והסוגים של התגובה לפעולה מאתר אחר (webhook) מוגדרים במפרט ה-API. כל בקשת webhook מכילה שתי כותרות: X-Signature ו-X-Signature-Timestamp.

הכותרת X-Signature מכילה חתימת webhook בפורמט הבא: primary=<primary_signature> secondary=<secondary_signature>

החתימות הראשית והמשנית הן תקציר הודעה (digest) בקידוד base64 של sha256 של הסודות הראשוניים או המשניים של ה-webhook, בהתאמה, עם מחרוזת משורשרת של הכותרת X-Signature-Timestamp ומטען ה-JSON של הבקשה.

הדוגמה הבאה מציגה הטמעה של הרשאה לבקשות של webhook באפליקציית Ruby on Rails לדוגמה:

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

סקירה כללית

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

מוצג תרשים של שיחה בפלטפורמת צ&#39;אט API.

יצירת משתמשי קצה

  • כדי ליצור צ'אטים, צריך לציין מזהה תקף של משתמש קצה. כלומר, משתמש קצה צריך להיות קיים במערכת Contact Center AI Platform לפני שיוצרים צ'אט.

  • משתמשי קצה מזוהים באופן ייחודי באמצעות המאפיין identifier, שהוא ערך מחרוזת שמסופק על ידי הצרכן. יכול להיות שמשתמש קצה כבר קיים במערכת אם הוא השתמש בערכות ה-SDK לאינטרנט או לנייד. נקודת הקצה POST /end_users מיושמת כפעולת upsert אידמפוטנטית, כך שאם מנסים ליצור משתמש קצה קיים מחדש, כל הנתונים שהשתנו יעודכנו ופרטי משתמש הקצה יוחזרו.

יצירת צ'אטים

כדי ליצור צ'אטים באמצעות API של פלטפורמת הצ'אט, פועלים לפי השלבים הבאים:

  1. טיפול במטענים ייעודיים (payloads) של צ'אטים חדשים: תהליך ההפעלה של הצ'אט מתבצע באופן אסינכרוני מהבקשה POST /chats. לכן, יכול להיות שהאירוע chat_created יתקבל לפני או אחרי התגובה של ה-API מנקודת הקצה ליצירת POST /chats. מומלץ לטפל באירוע chat_created ובתגובה של API ליצירת צ'אט באופן אידמפוטנטי כדי למנוע באגים אצל הצרכן.

  2. יצירת צ'אטים עם תמלילים: ה-API של פלטפורמת הצ'אט תומך ביצירת צ'אט עם תמליל של שיחה קיימת, בתרחיש שבו מתנהלת שיחה בפלטפורמה של לקוח, למשל עם צ'אטבוט, לפני שהיא נשלחת אל Contact Center AI Platform. כך הסוכן שעונה לצ'אט מקבל מידע נוסף על סשן הצ'אט, וזה עוזר למנוע מצב שבו משתמש הקצה חוזר על עצמו. למידע על פורמט מטען הייעודי (payload) של התמליל, ראו chat_platform_openapi.yaml.

הנציג הווירטואלי לבחירת תור

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

כדי להגדיר את הנציג הווירטואלי, צריך לבצע את השלבים הבאים:

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

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

    • דוגמה: "context": {"value": {"foo": "bar" } } יאפשר לסוכן הווירטואלי לקרוא את $session.params.context.foo עם הערך bar.

  3. הנציג הווירטואלי (בהתאם לאופן שבו הלקוח הגדיר אותו) משתמש בנתונים שמופיעים בשדה ההקשר כדי להעביר את הצ'אט לתור שנבחר. אם אין נציג זמין בתור היעד (למשל, בתרחיש שבו התור הוא מחוץ לשעות הפעילות או מעל הקיבולת), ההעברה תופסק והלקוח יקבל webhook שמציין את הסיבה להפסקת ההעברה ואת האפשרויות הזמינות להפסקת ההעברה.

הפניות לטיפול בבעיות ברמה גבוהה יותר: ממשק ה-API של פלטפורמת הצ'אט תומך בהפניות לטיפול בבעיות ברמה גבוהה יותר בצ'אט באפשרויות ההפניה הבאות, אם הן מוגדרות בפורטל Contact Center AI Platform:

  • אימייל: מבקשים ממשתמש הקצה לשלוח אימייל לתמיכה ומסיימים את הצ'אט. כשמשתמש קצה בוחר באפשרות הזו, אחרי שליחת האימייל, הלקוח צריך לסמן את הצ'אט כהפניה לפתרון עצמי וכסיום השיחה באמצעות נקודת הקצה PATCH /chats/:id עם הפרמטרים הבאים בגוף הבקשה: "status": "finished" , "escalation_id": &lt;id of escalation> , ו-"deflection_channel": "email"

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

  • המתנה נוספת לנציג שירות: אפשר להשתמש באפשרות הזו רק להעברות לטיפול ברמה גבוהה יותר עם הסיבה over_capacity. אם משתמש הקצה בוחר באפשרות הזו, צריך לעדכן את ההפניה לטיפול ברמה גבוהה יותר באמצעות PATCH chats/:id/escalations/:id with deflection_channel=human_agent

    • קישור להפניה חיצונית: מציג אזהרה למשתמש הקצה שלחיצה על קישור שמופיע בהפניה תסיים את הצ'אט. אם נבחר קישור, צריך לסיים את הצ'אט ולהשתמש ב-external_link לפרמטר deflection_channel

שליחה וקבלה של הודעות

כדי לשלוח או לקבל הודעות, פועלים לפי השלבים הבאים:

  1. תוכן טקסט: כדי לשלוח הודעות טקסט, משתמשים בנקודת הקצה POST /chats/:id/message כמו שמוגדר במסמך ה-API. כדי לקבל הודעות, מאזינים לאירוע webhook‏ message_received. חשוב לזכור שצרכן ה-API יקבל אירוע מסוג message_received לכל ההודעות שנשלחות באמצעות ה-API, כולל הודעות שנשלחות על ידי משתמש הקצה.

  2. תוכן של תמונות וסרטונים: כדי לשלוח תוכן של תמונות וסרטונים, המערכת מאחזרת כתובת URL להעלאה בחתימה מראש לשירות Cloud Storage שהוגדר מ-Contact Center AI Platform, מעלה לשירות האחסון ואז שולחת את כתובת ה-URL של האחסון במטען ייעודי (payload) של הודעה אל Contact Center AI Platform.

    1. אחזור כתובת URL עם חתימה מראש: אחזור כתובת URL עם חתימה מראש להעלאה מ-Contact Center AI Platform באמצעות POST /v1/chats/:chat_id/photos/upload או POST /v1/chats/:chat_id/videos/upload endpoints. נקודת הקצה הזו מחזירה כתובת URL עם חתימה מראש, יחד עם אוסף של שדות להעברה לשירות האחסון כשמעלים את הקובץ. ההגבלות הבאות חלות על העלאות עם חתימה מראש:

      • ‫Content-Type הוא image/jpeg לתמונות ו-video/mp4 לסרטונים.

      • הגודל המקסימלי של התמונות הוא 2MB. גודל הסרטון המקסימלי הוא 20MB.

      • זמן התפוגה הוא 5 דקות.

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

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

    2. העלאת קובץ המדיה: כדי להעלות את קובץ המדיה, שולחים בקשת POST לכתובת ה-URL החתומה מראש שאוחזרה בשלב 2א, עם הפרטים הבאים בגוף הבקשה:

      • ‫"file": הקובץ שרוצים להעלות

      • כל השדות שמוחזרים באובייקט fields בבקשת ה-URL החתום מראש.

    3. הוספת קובץ המדיה לצ'אט: כדי להוסיף את קובץ המדיה לצ'אט, צריך להשתמש בנקודת הקצה POST /chats/:id/photos או POST /chats/:id/videos. שימו לב: נקודת הקצה photos תומכת בשליחת מערך של תמונות, אבל נקודת הקצה video תומכת רק בסרטון אחד בכל פעם.

      • הערך של הפרמטר s3_path של גוף הבקשה צריך להיות זהה לערך של השדה key בתגובה של כתובת ה-URL עם החתימה מראש.

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

        • ‫url: כתובת ה-URL לקריאה בלבד ב-S3 או ב-Cloud Storage שבה נמצא הקובץ.

        • ‫media_id: המזהה של קובץ המדיה ב-Contact Center AI Platform. זהו המזהה שבו המדיה תצוין במטענים הייעודיים (payloads) של הצ'אט.

    4. שליחת קובץ המדיה כהודעה בצ'אט: כדי לשלוח את קובץ המדיה כהודעה בצ'אט, שולחים את מטען הייעודי (payload) הבא אל POST /chats/:id/message endpoint:

    {
  "from_user_id": <id of end user>,
  "message": {
    "type": <"photo" or "video">,
    "media_id": < media_id returned as described in 2.c >
  }
}

צפויים מפתחות JSON לא מוכרים בתגובות מה-API

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