נקודת קצה של סטטוס אימייל בכמות גדולה

במסמך הזה מתואר סטטוס נקודת הקצה של אימייל בכמות גדולה: POST /apps/api/v1/email/update_status. אפשר להשתמש בנקודת הקצה הזו כדי לשנות את הסטטוס של עד 100 סשנים של אימייל לסטטוס שאתם מציינים. לכל סשן אימייל שאתם מציינים, בדוח התגובה מצוין אם הוא עודכן, אם לא נדרש שינוי או אם אי אפשר לעדכן אותו, וגם הסיבה לכך. כלומר, שילובים יכולים לטפל בהצלחה חלקית ולזהות אילו סשנים עדיין דורשים תשומת לב.

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

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

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

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

אימות

במאמר אימות בסיסי מוסבר איך לאמת.

איך משתמשים בנקודת הקצה

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

אפשר לעדכן את סטטוס הסשן רק לסשנים של אימייל בתוך המופע שבבעלותו אסימון ה-API. מזהה סשן של סשן אימייל שלא נמצא במופע מסומן ב-"result": "failure" וב-"reason": "not_found".

מעבר של סשן לסטטוס closed יכול להפעיל סנכרון מוגדר של CRM עבור הסשנים האלה.

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

מעברים תקינים בין סטטוסים

כשמציינים את סטטוס היעד, אפשר לעבור רק מסטטוס מקור תקין לסטטוס היעד. כל סשן שהסטטוס הנוכחי שלו לא מהווה מקור תקף ליעד לא ישנה את הסטטוס שלו ויסומן ב-"reason": "invalid_transition".

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

סטטוס היעד	סטטוסים תקינים של מקורות
active	unopened, reopened, paused
paused	active
resolved	active
closed	paused, resolved

עדכון הסטטוס של סשן אימייל

כדי לעדכן את סטטוס ההפעלה באימייל, שולחים בקשת POST לנקודת הקצה הבאה:

https://YOUR_CCAAS_HOST/apps/api/v1/email/update_status

כוללים גוף בקשה במבנה הבא:

{
  "session_ids": [
    "SESSION_ID"
  ],
  "new_email_status": "NEW_EMAIL_STATUS"
}

מחליפים את מה שכתוב בשדות הבאים:

• ‫YOUR_CCAAS_HOST: המארח שלכם ב-CCAI Platform.

• ‫SESSION_ID: מערך מחרוזות של עד 100 מזהי סשנים של אימייל. לדוגמה, ["123", "456", "789"]. המערכת דוחה ערכים ריקים.

• ‫NEW_EMAIL_STATUS: סטטוס היעד שחל על כל סשן בבקשה. ערכים אפשריים: active,‏ paused,‏ resolved או closed.

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

{
  "existing_email_status": "EXISTING_EMAIL_STATUS"
}

מחליפים את EXISTING_EMAIL_STATUS באחד מהסטטוסים הבאים: unopened,‏ active,‏ paused,‏ resolved,‏ closed או reopened. אם כוללים את existing_email_status וסשן לא נמצא בסטטוס הזה, הוא נכשל עם הסיבה stale_state.

הפלט אמור להיראות כך:

{
  "results": [
    { "session_id": "123", "from_status": "active", "to_status": "paused", "result": "success" },
    { "session_id": "456", "result": "failure", "reason": "invalid_transition", "current_status": "closed" },
    { "session_id": "789", "result": "noop", "current_status": "paused" }
  ]
}

שדות תשובה

המערך results מכיל את השדות הבאים:

• ‫session_id: המזהה של סשן שהבקשה מיועדת אליו.

• from_status: הסטטוס של הסשן לפני העדכון.

• to_status: הסטטוס של הסשן אחרי העדכון.

• ‫result: התוצאה של העדכון. ערכים אפשריים:

  • success: הסטטוס של הפגישה עודכן. התוצאה כוללת את from_status ואת to_status.

  • failure: סטטוס הסשן לא עודכן. התוצאה כוללת את reason ואת current_status.

  • ‫noop: הפעילות כבר הייתה בסטטוס היעד, ולכן לא היה צורך בעדכון. התוצאה כוללת את current_status.

• ‫reason: הסיבה לכך שעדכון הסטטוס נכשל. ערכים אפשריים:

  • ‫not_found: אין סשן אימייל במופע שתואם למזהה הסשן שצוין. ניסיון חוזר לא יעזור.

  • ‫invalid_transition: הסטטוס הנוכחי של הסשן לא תקין כמקור לסטטוס היעד שצוין.

  • ‫stale_state: כללתם את existing_email_status והסטטוס הנוכחי של הסשן לא תאם.

  • ‫internal_error: אירעה שגיאה לא צפויה. אפשר לנסות לשלוח את הבקשה שוב.

• ‫current_status: סטטוס הסשן בזמן עיבוד הבקשה.

הודעות שגיאה

נקודת הקצה (endpoint) של סטטוס האימייל לרשימת תפוצה מחזירה את הודעות השגיאה הבאות:

• ‫400 Bad Request: גוף הבקשה פגום, session_ids חסר או ריק, session_ids מכיל יותר מ-100 רכיבים, new_email_status חסר או לא סטטוס מקובל, או ש-existing_email_status הוא לא סטטוס תקין.

• ‫401 Unauthorized: האימות נכשל או שפרטי הכניסה הם לא אסימון ApiUser.

• ‫404 Not Found: נקודת הקצה לא זמינה במופע שלכם.

המאמרים הבאים

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