הטמעה לדוגמה של EspoCRM

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

כדי להגדיר מכונה משלכם של EspoCRM, אפשר לעיין בדף ההתקנה של EspoCRM.

לפני שמתחילים

צריך לבצע את הפעולות הבאות:

• מגדירים את חומת האש כך שתאפשר תעבורה מ-CCAI Platform.

• יוצרים משתמש API במופע EspoCRM – לדוגמה, google_integration_user. מידע נוסף זמין במאמר בנושא API במסמכי העזרה של EspoCRM.

• יוצרים תפקיד במופע EspoCRM עם הפעולות Create,‏ Read ו-Update שמאפשרות גישה לרכיבים הבאים:

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

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

חשוב: ודאו שכל נקודות הקצה של ה-API שהגדרתם משתמשות באישור TLS תקין.

הגדרת חיבור מ-EspoCRM ל-CCAI Platform

כדי להגדיר חיבור מ-EspoCRM ל-CCAI Platform, צריך לבצע את השלבים הבאים:

1. בפורטל של פלטפורמת ה-CCAI, לוחצים על הגדרות > הגדרות למפתחים. אם לא מופיע התפריט הגדרות, לוחצים על תפריט.
2. בפלטפורמת נציגים, בוחרים באפשרות CRM בהתאמה אישית.
3. לוחצים על המתג הצגת CRM בפורטל CCAI Platform כדי להעביר אותו למצב מופעל.
4. בשדה כתובת URL לתצוגה, מזינים את כתובת ה-URL להטמעה בפורטל של פלטפורמת CCAI – לדוגמה, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
5. בקטע שיטת חיפוש במערכת CRM, בוחרים באפשרות Generic API.
6. כדי לבצע אימות באמצעות כותרת בהתאמה אישית, מבצעים את הפעולות הבאות:
   1. בקטע Authentication Method, בוחרים באפשרות Custom Header.
   2. לוחצים על הוספת שדה. מופיעה תיבת הדו-שיח הוספת שדה.
      1. בשדה Field Key, מזינים X-Api-Key.
      2. בשדה Field Value (ערך השדה), מזינים את מפתח ה-API שנוצר כשיוצרים משתמש API ב-EspoCRM.
      3. לוחצים על Save.
7. כדי להגדיר את כתובת ה-URL של החיפוש במערכת ה-CRM:
   1. בקטע כתובת URL לחיפוש ב-CRM, בשדה כתובת URL לחיפוש רשומה, מזינים את כתובת ה-URL לחיפוש רשומה – לדוגמה, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
   2. בשדה Account lookup URL (כתובת URL לחיפוש חשבון), מזינים את כתובת ה-URL לחיפוש חשבון – לדוגמה, https://YOUR_ESPO_DOMAIN/#Contact/view/{ACCOUNT_ID}.
   3. לוחצים על Save. ## הגדרת נקודות קצה ל-API

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

הגדרת נקודות קצה של חשבון API

בקטע הזה מוסבר איך להגדיר נקודות קצה (endpoints) של חשבונות API.

הגדרת נקודת קצה (endpoint) של שאילתה לחיפוש חשבון

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

1. ב-CCAI Platform, לוחצים על הגדרות > הגדרות למפתחים. אם לא מופיע התפריט הגדרות, לוחצים על תפריט.
2. בחלונית CRM, עוברים לקטע API account.
3. בקטע Find an account by query endpoint (איתור חשבון לפי נקודת קצה של שאילתה), לוחצים על Setup (הגדרה). מופיע הדף Generic API Endpoint Setup.
4. בשדה כתובת URL, מזינים את כתובת ה-URL של החשבון שרוצים לחפש – לדוגמה, https://YOUR_ESPO_DOMAIN/api/v1/Contact.
5. בשדה שיטה, בוחרים באפשרות GET.

6. כדי להגדיר פרמטרים של בקשה:

   1. כדי להגדיר את פרמטר הבקשה הראשון:
      1. לוחצים על הוספת שדה. מופיעה תיבת הדו-שיח הוספת שדה.
      2. בשדה Field Key, מזינים where[0][attribute].
      3. בשדה ערך השדה, מזינים phoneNumber.
      4. לוחצים על Save.

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

      מפתח השדה	ערך שדה
      where[0][attribute]	phoneNumber
      where[0][type]	equals
      where[0][value]	{PHONE_NUMBER}
      sortBy	createdAt
      asc	false

7. בשדה Response Data Location (מיקום נתוני התשובות), מזינים data.list.

8. לוחצים על Save.

9. לוחצים על חזרה להגדרות המפתח כדי לחזור לדף הגדרות המפתח.

הגדרת נקודת קצה של 'איתור חשבון לפי מזהה'

כדי להגדיר את נקודת הקצה Find an account by ID (איתור חשבון לפי מזהה):

1. בחלונית CRM, עוברים לקטע API account.
2. בקטע Find an account by ID endpoint (איתור חשבון לפי נקודת קצה של מזהה), לוחצים על Setup (הגדרה). מופיע הדף Generic API Endpoint Setup.
3. בשדה כתובת URL, מזינים את כתובת ה-URL של החשבון שרוצים לחפש – לדוגמה, https://YOUR_ESPO_DOMAIN/api/v1/Contact/{ACCOUNT_ID}.
   1. בשדה שיטה, בוחרים באפשרות GET.
4. מגדירים את מיקום נתוני התגובות לערך data.
5. לוחצים על Save.
6. לוחצים על חזרה להגדרות המפתח כדי לחזור לדף הגדרות המפתח.

הגדרת נקודת קצה ליצירת חשבון

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

1. בחלונית CRM, עוברים לקטע API account.
2. בקטע Create an account endpoint (יצירת נקודת קצה לחשבון), לוחצים על Setup (הגדרה). מופיע הדף Generic API Endpoint Setup.
3. בשדה כתובת URL, מזינים את כתובת ה-URL של החשבון שרוצים לחפש – לדוגמה, https://YOUR_ESPO_DOMAIN/api/v1/Contact.
4. בקטע Method (שיטה), בוחרים באפשרות POST (פרסום).

5. כדי להגדיר פרמטרים של בקשה:

   1. כדי להגדיר את פרמטר הבקשה הראשון:
      1. בקטע Request Parameters (פרמטרים של בקשה), לוחצים על Add field (הוספת שדה). מופיעה תיבת הדו-שיח הוספת שדה.
      2. בשדה Field Key, מזינים phoneNumber.
      3. בשדה ערך השדה, מזינים {PHONE_NUMBER}.
      4. לוחצים על Save.

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

      מפתח הפרמטר	ערך הפרמטר
      phoneNumber	{PHONE_NUMBER}
      firstName	New Caller
      lastName	{CALL_ID}
      name	New Caller {CALL_ID}

6. מגדירים את מיקום נתוני התגובות לערך data.

7. מגדירים את Object ID location ל-id.

8. לוחצים על Save.

9. לוחצים על חזרה להגדרות המפתח כדי לחזור לדף הגדרות המפתח.

הגדרת נקודת קצה לעדכון חשבון

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

1. בחלונית CRM, עוברים לקטע API account.
2. כדי לעדכן נקודת קצה של חשבון, לוחצים על הגדרה. מופיע הדף Generic API Endpoint Setup.
3. בשדה כתובת URL, מזינים את כתובת ה-URL של החשבון שרוצים לחפש – לדוגמה, https://YOUR_ESPO_DOMAIN/api/v1/Contact.
4. בקטע Method, בוחרים באפשרות PUT.

5. כדי להגדיר פרמטרים של בקשה:

   1. כדי להגדיר את פרמטר הבקשה הראשון:
      1. בקטע Request Parameters (פרמטרים של בקשה), לוחצים על Add field (הוספת שדה). מופיעה תיבת הדו-שיח הוספת שדה.
      2. בשדה Field Key, מזינים contactId.
      3. בשדה ערך השדה, מזינים {PHONE_NUMBER}.
      4. לוחצים על Save.

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

      מפתח הפרמטר	ערך הפרמטר
      contactId	{PHONE_NUMBER}
      phoneNumber	New Caller

6. מגדירים את מיקום נתוני התגובות לערך data.

7. לוחצים על Save.

8. לוחצים על חזרה להגדרות המפתח כדי לחזור לדף הגדרות המפתח.

הגדרת נקודות קצה של רשומות API

בקטע הזה מוסבר איך להגדיר נקודות קצה (endpoints) של רשומות API.

הגדרת נקודת קצה (endpoint) של חיפוש רשומה לפי שאילתה

כדי להגדיר את נקודת הקצה Find a record by query, פועלים לפי השלבים הבאים:

1. בחלונית CRM, עוברים לקטע API record.
2. בקטע Find a record by query endpoint (חיפוש רשומה לפי נקודת קצה של שאילתה), לוחצים על Setup (הגדרה). מופיע הדף Generic API Endpoint Setup.
3. בשדה כתובת URL, מזינים את כתובת ה-URL של החשבון שרוצים לחפש – לדוגמה, https://YOUR_ESPO_DOMAIN/api/v1/Case.
4. בשדה שיטה, בוחרים באפשרות GET.

5. כדי להגדיר פרמטרים של בקשה:

   1. כדי להגדיר את פרמטר הבקשה הראשון:
      1. בקטע Request Parameters (פרמטרים של בקשה), לוחצים על Add field (הוספת שדה). מופיעה תיבת הדו-שיח הוספת שדה.
      2. בשדה Field Key, מזינים where[0][attribute].
      3. בשדה ערך השדה, מזינים contactId.
      4. לוחצים על Save.

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

      מפתח השדה	ערך שדה
      where[0][attribute]	contactId
      where[0][type]	equals
      where[0][value]	{ACCOUNT_ID}
      contactId	{ACCOUNT_ID}
      sortBy	createdAt
      asc	false

6. בשדה Response Data Location (מיקום נתוני התשובות), מזינים data.list.

7. לוחצים על Save.

8. לוחצים על חזרה להגדרות המפתח כדי לחזור לדף הגדרות המפתח.

הגדרת נקודת קצה של Find a record by ID (איתור רשומה לפי מזהה)

המאפיין הזה משמש לעיתים קרובות באינטראקציות שמבוססות על SDK, והוא מאפשר להעביר מזהה רשומה ספציפי כדי לשייך אליו את האינטראקציה. כדי להגדיר את נקודת הקצה Find a record by ID, מבצעים את השלבים הבאים:

1. בחלונית CRM, עוברים לקטע API record.
2. בקטע Find a record by ID endpoint (איתור רשומה לפי נקודת קצה של מזהה), לוחצים על Setup (הגדרה). מופיע הדף Generic API Endpoint Setup.
3. בשדה כתובת URL, מזינים את כתובת ה-URL של החשבון שרוצים לחפש – לדוגמה, https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
4. בשדה שיטה, בוחרים באפשרות GET.
5. בשדה Response Data Location (מיקום נתוני התשובות), מזינים data.
6. לוחצים על Save.
7. לוחצים על חזרה להגדרות המפתח כדי לחזור לדף הגדרות המפתח.

הגדרת נקודת קצה ליצירת רשומה

כדי להגדיר את Create a record endpoint:

1. בחלונית CRM, עוברים לקטע API record.
2. בקטע Create a record endpoint, לוחצים על Setup. מופיע הדף Generic API Endpoint Setup.
3. בשדה כתובת URL, מזינים את כתובת ה-URL של החשבון שרוצים לחפש – לדוגמה, https://YOUR_ESPO_DOMAIN/api/v1/Case.
4. בקטע Method (שיטה), בוחרים באפשרות POST (פרסום).

5. כדי להגדיר פרמטרים של בקשה:

   1. כדי להגדיר את פרמטר הבקשה הראשון:
      1. בקטע Request Parameters (פרמטרים של בקשה), לוחצים על Add field (הוספת שדה). מופיעה תיבת הדו-שיח הוספת שדה.
      2. בשדה Field Key, מזינים description.
      3. בשדה ערך השדה, מזינים CALL Session:{CALL_ID}.
      4. לוחצים על Save.

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

      מפתח הפרמטר	ערך הפרמטר
      description	Call Session: {CALL_ID}
      name	Inbound Call from {ANI}
      contactId	{ACCOUNT_ID}
      status	New
      cchatId	{CHAT_ID}
      ccallId	{CALL_ID}
      cChannel	{CHANNEL}
      Type	{SESSION_TYPE}

6. בשדה Response Data Location (מיקום נתוני התשובות), מזינים data.

7. בשדה Object ID Location (מיקום מזהה האובייקט), מזינים את הערך id.

8. לוחצים על Save.

9. לוחצים על חזרה להגדרות המפתח כדי לחזור לדף הגדרות המפתח.

הגדרת נקודת קצה לעדכון רשומה

כדי להגדיר את נקודת הקצה Update a record, פועלים לפי השלבים הבאים:

1. בחלונית CRM, עוברים לקטע API record.
2. בקטע Update a record endpoint (עדכון נקודת קצה של רשומה), לוחצים על Setup (הגדרה). מופיע הדף Generic API Endpoint Setup.
3. בשדה כתובת URL, מזינים את כתובת ה-URL של החשבון שרוצים לחפש – לדוגמה, https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
4. בקטע Method, בוחרים באפשרות PUT.

5. כדי להגדיר פרמטרים של בקשה:

   1. כדי להגדיר את פרמטר הבקשה הראשון:
      1. בקטע Request Parameters (פרמטרים של בקשה), לוחצים על Add field (הוספת שדה). מופיעה תיבת הדו-שיח הוספת שדה.
      2. בשדה Field Key, מזינים parentId.
      3. בשדה ערך השדה, מזינים {RECORD_ID}.
      4. לוחצים על Save.

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

      מפתח הפרמטר	ערך הפרמטר
      parentId	{RECORD_ID}
      parentType	Case
      status	New
      description	{TICKET_DESCRIPTION}

6. בשדה Response data location (מיקום נתוני התגובה), מזינים data.

7. לוחצים על Save.

8. לוחצים על חזרה להגדרות המפתח כדי לחזור לדף הגדרות המפתח.