טיפול בשגיאות, ניסיונות חוזרים וסדר הקריאות במערכת CRM בהתאמה אישית (API גנרי)

במסמך הזה מתוארת ההתנהגות של התכונה "ניהול קשרי לקוחות (CRM) בהתאמה אישית" (API גנרי) בפלטפורמת CCAI, כשנקודות הקצה של ניהול קשרי הלקוחות מחזירות תשובות שהן לא HTTP 200 "Success.". המסמך מיועד לשמש כחומר עזר להתנהגות של משלבים שמגדירים נקודות קצה של חשבונות API ושל רשומות API.

סדר הביצוע והקשרים ברמה גבוהה

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

  1. פעולות ברמת החשבון (חשבון API) – איש קשר

    דוגמאות:

    • מוצאים איש קשר.

    • ליצור איש קשר.

    • לעדכן איש קשר.

  2. פעולות ברמת הרשומה (רשומת API) – כרטיס תמיכה או פנייה לתמיכה

    דוגמאות:

    • מחפשים כרטיס.

    • פותחים כרטיס תמיכה.

    • לעדכן כרטיס.

  3. פעולות אחרי הסשן (אם הוגדרו)

    דוגמאות:

    • מוסיפים תגובה או הערה.

    • מעלים קובץ מצורף או תמליל.

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

בשלבים מוקדמים יותר בדרך כלל נוצרים מזהים שבהם אפשר להשתמש בשלבים מאוחרים יותר. לדוגמה, אפשר להעביר contact_id ליצירת כרטיס כשהוא נכלל בתבנית המטען הייעודי (payload) של נקודת הקצה, ונדרש ticket_id לפעולות שאחרי הסשן בהגדרות טיפוסיות של API גנרי. שימו לב שלא כל נקודת קצה מוגדרת לחילוץ מזהה – עיינו בקטע ניואנס חשוב: ‎2xx + מזהה חסר בנקודות קצה לחילוץ מזהים.

ניואנס חשוב: 2xx + מזהה חסר בנקודות קצה לחילוץ מזהים

לא כל נקודת קצה מותאמת אישית של מערכת CRM מחלצת מזהה מהתגובה שהיא מקבלת. ההתנהגות הזו חלה רק על נקודות קצה שמוגדרות עם response_data_location ו-(לנקודות קצה של יצירה) custom_id_location – בדרך כלל נקודות קצה של חיפוש (חילוץ מזהה של רשומה קיימת) ונקודות קצה של יצירה (חילוץ מזהה של רשומה שנוצרה לאחרונה). נקודות קצה כמו תגובות, קבצים מצורפים ועדכונים לא מחלצות מזהים מהתגובות שלהן.

ההשפעה של מזהה חסר על נקודות קצה לחילוץ מזהים

  • לנקודות קצה (endpoints) של חיפוש: תגובה מסוג 200 OK ללא רשומה תואמת (ולכן ללא מזהה שניתן לחלץ) היא התנהגות רגילה של "לא נמצא". אם במכונה שלכם מופעלת האפשרות skip_account_creation או skip_record_creation, הפלטפורמה תמשיך במכוון במורד הזרם עם ערך null של contact_id או ticket_id במקום לנסות ליצור. זו התנהגות צפויה בהגדרות האלה, ולא מדובר בהגדרה שגויה.

  • בנקודות קצה מסוג create: אם התגובה 200 OK לא כוללת את המזהה החדש שנוצר במיקום שהוגדר, יש בעיה בהגדרה או בחוזה התגובה. בקשת ה-HTTP בוצעה בהצלחה, ולכן לא יופעלו ניסיונות חוזרים, אבל יכול להיות שהשלבים הבאים ימשיכו עם נתונים חסרים.

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

הנחיות לחברות מתאמות

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

  • בפעולות חיפוש, אפשר להחזיר את הערך 200 OK אם אין התאמה. אם המכונה שלכם מסתמכת בכוונה על דפוסי "חיפוש בלי יצירה" (לדוגמה, skip_account_creation = true), תעדו את ההחלטה הזו כדי שנקודות הקצה בהמשך יידעו איך לטפל במזהים חסרים בצורה חלקה.

  • במהלך הבדיקה, צריך לוודא ש:

    • בנקודות קצה ליצירה, המזהה מופיע באופן מהימן בתגובה ובמיקום המדויק שהוגדר ב-CRM בהתאמה אישית.

    • בנקודות קצה (endpoints) של חיפוש, ההתנהגות של הפלטפורמה במורד הזרם תואמת להגדרת דגל הדילוג של המכונה.

טיפול בשגיאות: סקירה כללית

כשנקודת קצה (endpoint) מחזירה תגובה של כישלון (לא 2xx) או לא מגיבה:

  • הפלטפורמה עשויה לנסות שוב לשלוח את הבקשה:

    • פעם אחת באופן מיידי עבור סטטוסים מסוימים.

    • במשך תקופה ארוכה יותר, במקרים של כשלים שאפשר לנסות שוב.

  • יכול להיות ששלבים במורד הזרם יתעכבו בזמן שהפלטפורמה תמשיך לנסות שוב שלב במעלה הזרם.

  • חלק מהכשלים נחשבים ככאלה שלא ניתן לנסות שוב (למשל, כשלים בהגדרה או באימות).

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

כללי שרשור ויחסי תלות

ההתנהגות של מערכת ה-CRM בהתאמה אישית כפופה להגדרות ה-CRM של המכונה שלכם – במיוחד ההגדרות שמתועדות בקטע דילוג על יצירת חשבון ורשומה ב-CRM. במאמר הזה אנחנו מתייחסים להגדרות האלה לפי השמות שלהן בהגדרות של הקצה העורפי (skip_account_creation,‏ skip_account_lookup,‏ skip_record_creation), כי ככה הן מופיעות בדוגמאות הבאות להגדרות JSON.

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

ההשפעה של כשלים בחשבון על פעולות התיעוד

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

בהתאם להגדרות האישיות, הפלטפורמה יכולה:

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

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

מה המשמעות מבחינת נקודות הקצה שלך

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

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

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

ההשפעה של כשלים בהקלטה על פעולות אחרי הפגישה

בהגדרות API כלליות שבהן מוגדר חיפוש כרטיסים, הפלטפורמה לא שולחת קריאות לאחר סשן, כמו call_finished,‏ chat_finished,‏ email_finished,‏ save_call_recording,‏ save_chat_history,‏ update_ticket ו-done_ticket, עד שקיים ticket_id.

אם נקודת קצה (endpoint) של אחרי סשן מופעלת בלי ticket_id, בדרך כלל זה מצביע על אחד מהמצבים הבאים:

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

  • בתבנית המטען הייעודי (payload) הושמט המשתנה ticket_id, וזו בעיה בהגדרה שכדאי לבדוק.

מה המשמעות מבחינת נקודות הקצה שלך

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

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

התנהגות של ניסיון חוזר והשהיה

ניסיונות חוזרים מתרחשים בשלוש שכבות:

  1. ניסיון חוזר מיידי ברמת ה-HTTP (ניסיון שני מהיר).

  2. ניסיון חוזר ברמת המתאם (שחזור מהיר של כשלים ברשת ותגובות זמניות ספציפיות).

  3. ניסיונות חוזרים ברמת הפקודה (ניסיונות חוזרים של זנב ארוך לאורך ימים).

ניסיון חוזר מיידי ברמת ה-HTTP (ניסיון חוזר מהיר)

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

  • 408, 413, 429, 500, 502, 503, 504, 521, 522 וגם 524.

ניסיון חוזר ברמת המתאם (שחזור רשת מהיר)

בין קריאת ה-HTTP לבין התזמון ברמת הפקודה, שכבת ניסיון חוזר ביניים במתאם ה-CRM‏ (command_runner.js) מטפלת בכשלים שלא מייצרים תגובת HTTP בכלל, או שתואמים להודעות זמניות ספציפיות:

  • הוספה מיידית לתור מחדש: מופעלת על ידי שגיאות ברמת ה-TCP/socket‏ – ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE, EAI_AGAIN. אלה כשלים ברשת שמתרחשים לפני שמתקבלת תגובת HTTP.

  • ניסיון חוזר אחרי 30 שניות: מופעל כשהודעת השגיאה היא "Too Early" (HTTP 425),‏ "Service Unavailable" או "Unordered Collection".

  • לא ניתן לנסות שוב בשכבה הזו: כל השאר עובר ללוח הזמנים לניסיון חוזר ברמת הפקודה (שכבה 3).

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

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

ניסיונות חוזרים ברמת הפקודה (כ-7 ימים, 14 ניסיונות)

אם פעולה נכשלת ואפשר לנסות אותה שוב, הפלטפורמה עשויה לנסות אותה שוב עד 14 פעמים במשך כ-7 ימים, לפי לוח הזמנים הבא:

  10s → 1m → 5m → 30m → 1h → 6h → 6h → 12h → 1d → 1d → 1d → 1d → 1d → 1d

התנהגות הניסיון החוזר של הזנב הארוך יכולה לחול על:

  • פעולות בחשבון.

  • פעולות הקלטה.

  • פעולות אחרי הסשן.

כשלים שלא ניתן לנסות שוב

חלק מהכשלים נחשבים ככאלה שלא ניתן לנסות שוב, לדוגמה:

  • כשלים בהגדרה או באימות (לדוגמה, נקודות קצה נדרשות לא מוגדרות או מוגדרות באופן שגוי).

  • קטגוריות מסוימות של שגיאות פנימיות שזוהו על ידי הפלטפורמה.

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

זמן קצוב לתפוגה וכשלים ברשת

הפלטפורמה מטפלת בשני נתיבים נפרדים:

  1. זמני קצובים לתפוגה ברמת האפליקציה: כשחורגים מהזמן הקצוב לתפוגה של HTTP שהוגדר (הבקשה נשלחה אבל לא התקבלה תשובה), הפלטפורמה מעלה שגיאה פנימית שאפשר לנסות שוב ברמת הפקודה (שכבה 3). כלומר, הבקשה תפעל לפי לוח הזמנים הרגיל של השהיה לפני ניסיון חוזר (עד 14 ניסיונות חוזרים במשך כ-7 ימים).

  2. שגיאות ברמת TCP/socket: כשהחיבור נכשל ברמת הרשת לפני שמתקבלת תגובת HTTP (לדוגמה, ETIMEDOUT,‏ ESOCKETTIMEDOUT ו-ECONNREFUSED), שכבת המתאם (שכבה 2) קולטת את השגיאות האלה ומכניסה את הפקודה לתור מחדש באופן מיידי. ההתאוששות מהכשלים האלה בדרך כלל מהירה יותר – לרוב תוך כמה שניות, ולא לפי לוח הזמנים של 7 הימים.

למה ההבדל חשוב

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

  • אם יש כשל ברמת הרשת (לא ניתן להגיע לשרת בכלל), המערכת תנסה שוב מהר יותר.

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

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

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

טבלת סיכום התוצאות

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

תוצאת הסריקה דוגמאות ניסיון חוזר מיידי של HTTP? ניסיונות חוזרים לזנב ארוך (כ-7 ימים)? ההשפעה בהמשך
הצלחה של נקודת קצה לחילוץ מזהים ‫2xx + המזהה הצפוי נמצא במיקום התגובה שהוגדר. לא לא התהליך ממשיך עם המזהה שחולץ.
חיפוש ללא התאמה 2xx אבל לא נמצאה רשומה במיקום שהוגדר. לא לא התנהגות רגילה של "לא נמצא". כשהאפשרות skip_account_creation או skip_record_creation מופעלת, המערכת ממשיכה בכוונה עם מזהים ריקים.
יצירת 2xx חוזרת ללא מזהה ‫2xx מנקודת קצה (endpoint) ליצירה, אבל המזהה של הרשומה החדשה חסר במיקום שהוגדר. לא לא יכול להיות שהתהליך ימשיך בלי הנתונים החסרים. צריך להתייחס לזה כבעיה בהגדרה או בחוזה התגובה.
הצלחה בנקודת קצה (endpoint) שלא מחלצת מזהה ‫2xx מנקודות קצה (endpoints) כמו פעולות של הערות, עדכונים או קבצים מצורפים שלא מחלצות מזהים. לא לא ההמשך של התהליך מתבצע בהתאם לשרשרת הפקודות ולהגדרות של המכונה.
שגיאה זמנית 408, 413, 429, 500, 502, 503, 504, 521, 522 וגם 524. כן (שני ניסיונות בסך הכול) לרוב כן יכול להיות ששלבים בהמשך יתעכבו בזמן שהמערכת מנסה שוב.
שגיאות אחרות ‫400, ‏401, ‏403, ‏404 ועוד 4xx/5xx. לא לרוב כן יכול להיות ששלבים בהמשך יתעכבו בזמן שהמערכת מנסה שוב.
כשל בהגדרה או באימות הגדרה שגויה, נקודות קצה חסרות. לא רלוונטי לא יכול להיות שהשרשרת תיעצר או תושלם באופן חלקי, בהתאם להגדרות האישיות.
כשל ברמת הרשת (TCP/socket) ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE וגם EAI_AGAIN. לא רלוונטי לא (מטופל על ידי מתאם שכבה 2) המתאם מוסיף את הבקשה לתור מחדש באופן מיידי. ההתאוששות בדרך כלל מהירה (שניות). יכול להיות שיהיה עיכוב קל בשלבים הבאים.
זמן קצוב לתפוגה ברמת האפליקציה ‫HTTP timeout exceeded (לא התקבלה תשובה). לא רלוונטי לרוב כן (שכבה 3) יכול להיות ששלבים בהמשך יתעכבו בזמן שמתרחשים ניסיונות חוזרים ברמת הפקודה.

דוגמה מעשית עם הגדרת API גנרי מינימלי

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

הגדרות ברמת המכונה

{
  "lookup_method": "genericApi",
  "auth_method": "basic",
  "basic_auth_username": "ccai-integration",
  "basic_auth_password": "<secret>",
  "api_request_timeout": 10,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}",
  "contact_lookup_url": "https://crm.example.com/api/contacts/{ACCOUNT_ID}",
  "skip_account_lookup": false,
  "skip_account_creation": false,
  "skip_record_creation": false
}

צורות של תגובות

מבנה התגובה של מערכת ה-CRM משתנה בהתאם ללקוח. ‫response_data_location הוא נתיב בסגנון lodash שמגיע לאובייקט הרלוונטי בתוך גוף התגובה המנותח. אין דרישה לעטוף את התשובות בשדה data ברמה העליונה – הדוגמאות הבאות מציגות צורות שטוחות מציאותיות כברירת מחדל.

לדוגמה, במערכת CRM שבה המשאבים מקוננים ב-data.contact, צריך להגדיר את response_data_location: "data.contact" ואת גוף התגובה { "contact": { "id": "c_99812" } }. שאר ההגדרות לא משתנות.

נקודת קצה 1 – contact_find_endpoint

חיפוש איש קשר לפי מספר טלפון או כתובת אימייל.

{
  "request_url": "https://crm.example.com/api/contacts/search?phone={PHONE_NUMBER}&email={EMAIL}",
  "request_method": "GET",
  "request_parameters": {},
  "response_data_location": "data"
}

הצלחה: איש הקשר נמצא

200 OK
Content-Type: application/json
{ "id": "c_42018", "first_name": "Jane", "last_name": "Doe" }

איש הקשר לא נמצא

404 Not Found

הפלטפורמה מתייחסת ל-404 כאל "לא נמצא" (לא שגיאה). אם הערך של skip_account_creation הוא false, התהליך ממשיך אל contact_create_endpoint.

תבנית חלופית של "לא נמצא": גם היא תקינה

200 OK
{}

בחלק ממערכות ה-CRM מוחזר הערך 200 OK עם נתונים ריקים במקום 404 כשאין רשומה תואמת. הפלטפורמה מטפלת בשניהם באופן שווה – שניהם מפעילים את השלב הבא (יצירה, אם היא מופעלת).

כשל זמני

503 Service Unavailable
}

מפעיל ניסיון חוזר מיידי של HTTP בשכבה 1 (2 ניסיונות בסך הכול). אם הפעולה עדיין נכשלת, המערכת עוברת לניסיונות חוזרים ברמת הפקודה של שכבה 3.

נקודת קצה 2 – contact_create_endpoint

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

{
  "request_url": "https://crm.example.com/api/contacts",
  "request_method": "POST",
  "request_parameters": {
    "first_name": "{FIRST_NAME}",
    "last_name": "{LAST_NAME}",
    "email": "{EMAIL}",
    "phone": "{PHONE_NUMBER}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

יצירה מוצלחת

201 Created
{ "id": "c_99812", "first_name": "John", "last_name": "Doe" }

‫2xx אבל חסר מזהה במיקום שהוגדר

200 OK
{}

נקודת הקצה החזירה את הערך 200 OK בלי id במיקום שהוגדר. הפלטפורמה מתעדת אזהרה ביומן ומעבירה ערך null של contact_id במורד הזרם (לא נזרקת חריגה, אין ניסיון חוזר). התייחסו לזה כאל בעיה בהגדרה – response_data_location ו-custom_id_location אמורים להניב מזהה באופן מהימן לכל 2xx שנקודת הקצה מחזירה מהנתיב הזה.

נקודת קצה 3 – case_create_endpoint

יצירת כרטיס תמיכה. הערך של contact_id מהשלב הקודם זמין בתור {ACCOUNT_ID}.

{
  "request_url": "https://crm.example.com/api/cases",
  "request_method": "POST",
  "request_parameters": {
    "subject": "{TICKET_SUBJECT}",
    "description": "{TICKET_DESCRIPTION}",
    "contact_id": "{ACCOUNT_ID}",
    "channel": "{CHANNEL}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

יצירה מוצלחת

201 Created
{ "id": "case_77103", "status": "new" }

באמצעות response_data_location: "data", הפלטפורמה פותרת את הנתיב לגוף התגובה המנותח. לאחר מכן, הוא קורא את השדה ב-custom_id_location: "id" ← ticket_id = "case_77103", שמועבר לפוסט-סשן.

נקודת קצה 4 – case_comment_endpoint

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

{
  "request_url": "https://crm.example.com/api/cases/{RECORD_ID}/comments",
  "request_method": "POST",
  "request_parameters": {
    "body": "{COMMENT_BODY}",
    "agent_email": "{AGENT_EMAIL}",
    "channel": "{CHANNEL}",
    "duration": "{CALL_DURATION}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  }
}

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

וריאציה: יצירת החשבון מושבתת

הדוגמה הזו דומה מאוד לדוגמה הקודמת של הגדרת API גנרי מינימלי, אבל כאן המכונה לא מאפשרת ליצור אנשי קשר ב-CRM. בזמן שחיפוש החשבון פועל, יצירת החשבון לא פועלת.

שינוי הגדרות המכונה

{
  "skip_account_creation": true,
  "skip_account_lookup": false
}

השינויים בהגדרות של המכונה כוללים את ההתנהגויות הבאות:

  • השלב בחשבון מתייחס רק לשיחות אל contact_find_endpoint. אם לא נמצא איש קשר, לא תתבצע שיחה אל contact_create_endpoint.

  • שלב ההקלטה מקבל ערך null של contact_id. הפלטפורמה ממשיכה ליצירת כרטיס בלי contact_id – {ACCOUNT_ID} נפתר לריק, והשדה contact_id מושמט לחלוטין מהמטען הייעודי (payload) של case_create_endpoint.

  • זה אומר שנקודת הקצה ליצירת כרטיסים צריכה להיות מסוגלת ליצור כרטיסים בלי contact_id בהגדרה הזו. אם מערכת ה-CRM שלכם דורשת איש קשר משויך לכל כרטיס, ההגדרה הזו לא תואמת.

דפוס הגנתי בcase_create_endpoint

בלי contact_id, למערכת ה-CRM יש פחות הקשר לגבי המתקשר מאשר בדרך כלל. אפשר להשתמש בכלי העזר =DEFAULT_VALUE כדי לתעד את הפרטים המזהים שזמינים בבקשה ולהעביר אותם כאות חלופי:

"request_parameters": {
  "subject": "{TICKET_SUBJECT}",
  "contact_id": "{ACCOUNT_ID}",
  "contact_origin": "=DEFAULT_VALUE(\"{EMAIL}\", \"{PHONE_NUMBER}\", \"anonymous\")"
}

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

וריאציה: תהליך חיפוש כרטיס בלבד (ללא יצירת רשומה)

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

שינוי הגדרות המכונה

{
  "skip_record_creation": true,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}"
}

השינויים כוללים את ההתנהגויות הבאות:

  • שלב הרישום קורא ל-case_find_endpoint ומשתמש בכרטיס שהוחזר. אם לא נמצא כרטיס, השרשרת נעצרת בשלב הרישום – case_create_endpoint לא מופעל.

  • נקודות קצה (endpoints) אחרי סשן (case_comment_endpoint,‏ case_update_endpoint ודומות) נשלחות רק כשחיפוש הכרטיס מצליח. ההגנה של ready? בצד של Rails מבטיחה שהפקודות האלה יישארו בתור (ובסופו של דבר יפוג תוקפן) אם לא יתממש אף ticket_id.

  • השלכה מעשית: בהגדרה הזו, נקודות הקצה (endpoints) שלכם אחרי הסשן יקבלו רק סשנים שקשורים לכרטיס מוכר. אתם לא צריכים לטפל בהסתעפות "missing ticket_id".

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

"request_parameters": {
  "...your fields...": "...",
  "ccai_session_key": "{SESSION_TYPE}-{SESSION_ID}"
}

באותה קריאה, כל ניסיון חוזר בכל נקודת קצה בשרשרת (חשבון > רשומה > אחרי הסשן) יפיק את אותו ccai_session_key. השתמשו בו כעוגן לביטול כפילויות בלוגיקה של היצירה או העדכון או ההוספה (upsert) של ה-CRM. לדוגמה, עדכון או הוספה (upsert) ב-(ccai_session_key, endpoint_kind) יספגו ניסיונות חוזרים באופן בטוח בלי ליצור רשומות כפולות.

יצירת נקודות קצה (endpoints) עמידות (טיפים לעיצוב ולאידמפוטנטיות)

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

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

    • משלבים את סוג הסשן עם מזהה הסשן, לדוגמה, call-12345 או chat-12345.

    • אל תסתמכו רק על call_id או על chat_id. יכולה להיות חפיפה בין מזהי הקול והצ'אט כי כל רצף יכול להתחיל ב-1.

  • אם קיבלתם בקשה שנראית כמו בקשה כפולה:

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

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

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

  • טיפול מפורש במזהים חסרים:

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

    • אם מוגדר חיפוש כרטיסים, לא צפוי ש-ticket_id יהיה חסר בקריאות אחרי סשן בהגדרות API גנריות רגילות. לפני שמתייחסים לבקשה כאל פעולה רגילה ללא השפעה, צריך לבדוק את ההגדרות של חיפוש הכרטיסים ואת התבניות של המטען הייעודי (payload).

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

פתרון בעיות וניראות

כשמאתרים באגים בשילוב של מערכת CRM בהתאמה אישית, חשוב לזכור את הדפוסים הבאים:

  • קריאות חוזרות לאותה נקודת קצה:

    • משווים בין חותמות הזמן לבין לוח הזמנים לניסיונות חוזרים בניסיונות חוזרים ברמת הפקודה (~7 ימים, 14 ניסיונות).

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

    • היומנים שמיוצאים מ-CCAI Platform יכולים לעזור לכם לראות את מזהה הסשן של השיחה או הצ'אט לצד אירועי API, כדי שתוכלו לעקוב אחריהם.

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

  • ניסיונות חוזרים "שלא ייפסקו":

    • בודקים את תגובות השגיאה שנקודת הקצה מחזירה.

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

  • נקודת הקצה (endpoint) לא הופעלה:

    • מומלץ לבדוק את הדברים הבאים:

      • השלבים הקודמים (חשבון/רשומה) הושלמו בהצלחה והתקבלו המזהים הנדרשים.

      • נקודת הקצה מוגדרת ומופעלת בצורה נכונה בהגדרות של מערכת ה-CRM המותאמת אישית.

    • אם נקודת קצה (endpoint) מושבתת או מוגדרת באופן שגוי, או אם יש תקלה בשלב מוקדם יותר בשרשרת, יכול להיות ששלבים מסוימים לא יפעלו.

  • יומנים תואמים:

    • מתעדים את הבקשה והתגובה המלאות בצד שלכם, כולל מזהה האינטראקציה (call_id / chat_id).

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