שילוב של Dialogflow עם Google Chat

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

ב-codelab הזה תלמדו איך Dialogflow מתחבר לממשקי API של Google Workspace כדי ליצור כלי לתזמון פגישות ביומן Google עם תשובות דינמיות ב-Google Chat.

אם עדיין לא הגדרתם את התהליך מה-Codelab הקודם או שאתם בטוחים שאתם יודעים להשתמש ב-Dialogflow וב-fulfillment, אתם יכולים להוריד את קוד לתחילת הדרך ואת הגדרות ה-Agent מכאן

https://github.com/googleworkspace/appointment-scheduler-codelab

דרישות מוקדמות

לפני שממשיכים, צריך להשלים את ה-codelabs הבאים:

1. איך יוצרים כלי לתזמון פגישות באמצעות Dialogflow
2. שילוב של Dialogflow עם Actions on Google
3. הסבר על ישויות ב-Dialogflow
4. הסבר על ביצוע פעולות באמצעות שילוב של Dialogflow עם יומן Google

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

מה תלמדו

• איך פורסים ומגדירים אפליקציית צ'אט ל-Google Chat
• איך יוצרים כרטיסי תצוגה ב-Google Chat
• איך יוצרים מטענים ייעודיים (payloads) בהתאמה אישית ב-Dialogflow Fulfillment

מה תפַתחו

• שילוב בין Dialogflow, ‏ Google Chat ויומן Google
• (אופציונלי) שילוב של מפות Google כדי להציג כרטיסים עם יותר מידע

הדרישות

• דפדפן אינטרנט וכתובת אימייל כדי להיכנס למסוף Dialogflow
• היומן ו-Google Chat מופעלים בדומיין שלכם ב-Google Workspace

אזהרה: כדי להשלים את ה-codelab הזה, צריך להשתמש בחשבון Google Workspace. אם תנסו להפעיל את ה-API באמצעות חשבון עם סיומת ‎ @gmail.com, תופיע שגיאה.

2. הפעלה והגדרה של Google Chat

נתחיל עם סוכן Dialogflow שיצרתם ב-codelabs הקודמים.

1. ב-Dialogflow console, לוחצים על .
2. בכרטיסייה כללי, גוללים אל מזהה הפרויקט ולוחצים על Google Cloud .

3. במסוף Google Cloud, לוחצים על תפריט הניווט ☰ > APIs & Services (ממשקי API ושירותים) > Library (ספרייה).
4. מחפשים את Google Chat API ולוחצים על הפעלה כדי להשתמש ב-API בפרויקט בענן של Google.
5. עכשיו נגדיר את אפליקציית צ'אט. עוברים לדף Configuration של ה-API. חשוב לדעת: לכל פרויקט ב-GCP יכולה להיות אפליקציית צ'אט אחת לכל היותר.

6. שדות Dialogflow אמורים להתמלא באפשרויות ההגדרה.
7. משנים את השדה 'כתובת ה-URL של הדמות' לתמונה הזו של מכונית: **https://fonts.gstatic.com/s/i/googlematerialicons/directions_car/v5/black-48dp/1x/gm_directions_car_black_48dp.png**
8. כדי להפעיל את אפליקציית Chat גם בצ'אטים ישירים וגם במרחבים, בוחרים באפשרות אפשר לשלוח הודעות ישירות לאפליקציה והאפליקציה פועלת במרחבים עם כמה משתמשים.

לוחצים על שמירה ויוצאים מ-Cloud Console.

3. שילובים נוספים של Dialogflow

‫Google Chat מופעל כברירת מחדל, אבל אם רוצים שהבוט יפעל בכמה פלטפורמות, אפשר לעבור לדף Integrations ב-Dialogflow Console ולהפעיל אותן.

4. בדיקה ב-Google Chat

אחרי שהגדרתם את אפליקציית Chat, אפשר להוסיף אותה למרחב ב-Chat ולבדוק אותה. פותחים את Google Chat ויוצרים מרחב משותף לבדיקה.

1. בפינה השמאלית העליונה של המרחב, לוחצים על התפריט הנפתח ובוחרים באפשרות הוספת אנשים ואפליקציות.
2. מחפשים את AppointmentScheduler ומוסיפים את האפליקציה למרחב.
3. עכשיו אפשר לקיים אינטראקציה עם האפליקציה שכבר יצרתם ב-Google, פשוט מקלידים @AppointmentScheduler במרחב.

אפשר לבדוק את הפלטפורמה הזו עם אותה קלט מה-Codelab הקודם:

1. משתמש: "‎@AppointmentScheduler Set an appointment for vehicle registration at 2 PM tomorrow.‎"
2. אפליקציית צ'אט: "בסדר, בוא נראה אם יש לנו מקום בשבילך. ‫24 באפריל, בשעה 14:00 זה מצוין!"

בשלב הבא נשתמש בהתאמות האישיות ב-Google Chat כדי להוסיף תשובות מועילות יותר.

5. כרטיסים מותאמים אישית ב-Google Chat

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

תגובת הטקסט הבסיסית נראית כך:

 {
  "text": "Your pizza delivery is here!"
}

דוגמה לתגובה בכרטיס עם ווידג'טים:

{
  "cards": [
    {
      "sections": [
        {
          "widgets": [
            {
              "image": { "imageUrl": "https://..." }
            },
            {
              "buttons": [
                {
                  "textButton": {
                    "text": "OPEN IN GOOGLE MAPS",
                    "onClick": {
                      "openLink": {
                        "url": "https://..."
                      }
                    }
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

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

6. מטענים ייעודיים (payloads) וכרטיסים ב-Chat

מטענים ייעודיים (payloads) ב-Dialogflow מאפשרים ליצור הודעות תשובה עשירות שספציפיות לפלטפורמה. כאן נוסיף את כרטיסי ה-JSON של Hangouts Chat, והסוכן יציג אותם למשתמש.

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

לוחצים על Google Chat, מבטלים את הסימון של Use responses from the DEFAULT tab as the first responses (שימוש בתשובות מהכרטיסייה DEFAULT כתשובות הראשונות), ואז לוחצים על ADD RESPONSES > Custom Payload (הוספת תשובות > מטען ייעודי (payload) בהתאמה אישית).

יוצג מבנה JSON.

מעתיקים ומדביקים את הקוד הבא. הגדרנו כרטיס עם ווידג'ט TextParagraph.

{
 "hangouts": {
   "header": {
     "title": "Appointment Scheduler"
   },
   "sections": [
     {
       "widgets": [
         {
           "textParagraph": {
             "text": "Welcome, I am the scheduler agent. Please request an appointment type and time."
           }
         }
       ]
     }
   ]
 }
}

לוחצים על שמירה ואז עוברים למרחב הבדיקה ב-Chat כדי לראות את הכרטיס. במרחב ב-Chat, מקלידים '@AppointmentScheduler hello'.

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

7. הוספת כרטיס ב-Fulfillment

עכשיו ניצור כרטיס עם כמה ווידג'טים כדי להציג פגישה מתוזמנת. נוסיף פונקציה בשם getGoogleChatCard שבה נעבד את הקלט: appointmentType,‏ date ו-time.

מוסיפים את הפונקציה שבהמשך לקוד ב-index.js בתחתית.

function getGoogleChatCard(appointmentType, date, time) {
   const cardHeader = {
     title: 'Appointment Confirmation',
     subtitle: appointmentType,
     imageUrl: ICON_IMAGE_URL,
     imageStyle: 'IMAGE',
   };
    const dateWidget = {
     keyValue: {
       content: 'Date',
       bottomLabel: date,
     },
   };
    const timeWidget = {
     keyValue: {
       content: 'Time',
       bottomLabel: time,
     },
   };

    const buttonWidget = {
     buttons: [
       {
         textButton: {
           text: 'View Appointment',
           onClick: {
             openLink: {
               url: CALENDAR_URL,
             },
           },
         },
       },
     ],
   };
    const infoSection = {widgets: [dateWidget, timeWidget,
     buttonWidget]};
    return {
     'hangouts': {
       'name': 'Confirmation Card',
       'header': cardHeader,
       'sections': [infoSection],
     },
   };
 }

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

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

return createCalendarEvent(dateTimeStart, dateTimeEnd, appointmentType).then(() => {
   agent.add(`Ok, let me see if we can fit you in. ${appointmentTimeString} is fine!.`);

   const dateString = dateTimeStart.toLocaleString(
     'en-US',
       {month: 'long', day: 'numeric'},
   );
   const dateParts = appointmentTimeString.split(',');
   const json = getGoogleChatCard(appointmentType, dateParts[0], dateParts[1]);
   const payload = new Payload(
       'hangouts',
       json,
       {rawPayload: true, sendAsMessage: true},
   );
   agent.add(payload);

 }).catch(() => {
   agent.add(`I'm sorry, there are no slots available for ${appointmentTimeString}.`);
 });
}

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

8. (אופציונלי) הוספה של ווידג'ט תמונה של מפות Google

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

1. מפעילים את Maps Static API במסוף Google Cloud, באותו אופן שבו הפעלתם את Calendar API ו-Google Chat API.
2. יוצרים מפתח API ושומרים אותו בפרויקט בדף APIs & Services במסוף. מידע נוסף על אחזור ושיטות מומלצות לשימוש במפתחות API עם מפות Google זמין כאן.
3. מעתיקים את מפתח ה-API ואת הקבועים הבאים לחלק העליון של הקובץ index.js

const API_KEY = 'YOUR_API_KEY';
const MAP_IMAGE_URL = 'https://maps.googleapis.com/maps/api/staticmap?center=Googleplex&zoom=14&size=200x200&key=' + API_KEY;
const ICON_IMAGE_URL = 'https://fonts.gstatic.com/s/i/googlematerialicons/calendar_today/v5/black-48dp/1x/gm_calendar_today_black_48dp.png';
const CALENDAR_URL = 'YOUR_CALENDAR_URL';

4. בשלב הבא מוסיפים ווידג'ט של תמונה לפונקציה getGoogleChatCard

  const mapImageWidget = {
    'image': {
      'imageUrl': MAP_IMAGE_URL,
      'onClick': {
        'openLink': {
          'url': MAP_IMAGE_URL,
        },
      },
    },
  };

5. מוסיפים את mapImageWidget לרשימת הווידג'טים במשתנה infoSection, שומרים ומפעילים.
6. כדאי לבדוק את אפליקציית צ'אט במרחב ב-Chat. אמורה להתקבל תגובה מתקדמת על סמך הקוד שהוספתם היום.

9. הסרת המשאבים

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

מחיקת סוכן Dialogflow

1. לוחצים על הסמל לצד הנציג הקיים.

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

10. מזל טוב

יצרתם צ'אט בוט ב-Dialogflow ושילבתם אותו עם יומן Google ועכשיו עם Google Chat. אתם מקצוענים ב-Google Workspace!

מידע נוסף

למידע נוסף, אפשר לעיין בדוגמאות הקוד בדף Dialogflow Github.