دمج Dialogflow مع Google Chat

1. قبل البدء

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية ربط Dialogflow بواجهات برمجة التطبيقات في Google Workspace لإنشاء "أداة جدولة المواعيد" المتكاملة مع "تقويم Google" والتي تتضمّن ردودًا ديناميكية في Google Chat.

إذا لم يكن لديك الإعداد من دروس البرمجة السابقة أو لم تكن واثقًا من Dialogflow والتنفيذ، يمكنك تنزيل رمز البداية وإعداد الوكيل من هنا

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

المتطلبات الأساسية

قبل المتابعة، عليك إكمال الدورات التدريبية التالية:

1. إنشاء أداة جدولة مواعيد باستخدام Dialogflow
2. دمج Dialogflow مع "المهام مع مساعد Google"
3. التعرّف على الكيانات في Dialogflow
4. فهم عملية التنفيذ من خلال دمج Dialogflow مع "تقويم Google"

عليك أيضًا فهم المفاهيم الأساسية في Dialogflow، ويمكنك الاطّلاع عليها من خلال الفيديوهات التالية المتوفّرة في مسار إنشاء روبوت محادثة باستخدام Dialogflow.

أهداف الدورة التعليمية

• كيفية نشر تطبيق محادثات Google Chat وضبط إعداداته
• كيفية إنشاء بطاقات عرض في Google Chat
• كيفية إنشاء حمولات مخصّصة في عملية التنفيذ في Dialogflow

ما ستنشئه

• عملية دمج بين Dialogflow وGoogle Chat و"تقويم Google"
• (اختياري) دمج "خرائط Google" مع البطاقات التفاعلية

المتطلبات

• متصفّح ويب وعنوان بريد إلكتروني لتسجيل الدخول إلى وحدة تحكّم Dialogflow
• تفعيل "تقويم Google" وGoogle Chat في نطاق Google Workspace

تحذير: يجب استخدام حساب Google Workspace لإكمال هذا الدرس العملي. سيؤدي استخدام حساب ينتهي بـ ‎ @gmail.com إلى حدوث خطأ عند محاولة تفعيل واجهة برمجة التطبيقات.

2. تفعيل Google Chat وضبط إعداداته

سنبدأ باستخدام وكيل Dialogflow الذي أنشأته في الدروس البرمجية السابقة.

1. في وحدة تحكّم Dialogflow، انقر على .
2. في علامة التبويب الإعدادات العامة، انتقِل إلى رقم تعريف المشروع، ثم انقر على Google Cloud .

3. في Google Cloud Console، انقر على قائمة التنقّل ☰ > واجهات برمجة التطبيقات والخدمات > المكتبة.
4. ابحث عن "Google Chat API"، ثم انقر على تفعيل لاستخدام واجهة برمجة التطبيقات في مشروعك على Google Cloud.
5. سنضبط الآن تطبيق محادثاتك، لذا انتقِل إلى صفحة الإعدادات الخاصة بواجهة برمجة التطبيقات. يُرجى العِلم أنّه يمكن أن يتضمّن كل مشروع على Google Cloud Platform تطبيق محادثات واحدًا على الأكثر.

6. من المفترض أن ترى حقول Dialogflow تملأ خيارات الإعداد.
7. غيِّر حقل "عنوان URL الخاص بالصورة الرمزية" إلى صورة السيارة هذه: **https://fonts.gstatic.com/s/i/googlematerialicons/directions_car/v5/black-48dp/1x/gm_directions_car_black_48dp.png**
8. لتفعيل تطبيق محادثاتك لكل من الرسائل المباشرة والمساحات، ضَع علامة في المربّعَين يمكن مراسلة التطبيق مباشرةً ويعمل التطبيق في المساحات التي تضمّ عدة مستخدمين.

انقر على حفظ واخرج من Cloud Console.

3- عمليات دمج إضافية في Dialogflow

يكون Google Chat مفعّلاً تلقائيًا، ولكن إذا أردت أن يخدم برنامج الدردشة الآلي منصات متعددة، يمكنك الانتقال إلى صفحة عمليات الدمج في Dialogflow Console لتفعيلها.

4. الاختبار في Google Chat

بعد إعداد تطبيق محادثات، لنضِفه إلى مساحة Chat ونجرِّبه. افتح Google Chat وأنشئ مساحة اختبار.

1. في أعلى يسار المساحة، انقر على القائمة المنسدلة واختَر إضافة مستخدمين وتطبيقات.
2. ابحث عن AppointmentScheduler وأضِف التطبيق إلى المساحة.
3. يمكنك الآن التفاعل مع التطبيق الذي سبق أن أنشأته في Google من خلال كتابة @AppointmentScheduler في المساحة.

جرِّبها على هذه المنصة باستخدام الإدخال نفسه من دروس الترميز التطبيقية السابقة:

1. المستخدم: "‎@AppointmentScheduler أريد تحديد موعد لتسجيل المركبة في الساعة 2 ظهرًا غدًا".
2. تطبيق محادثات: "حسنًا، دعني أرى ما إذا كان بإمكاننا إيجاد موعد لك. "الموعد في 24 أبريل الساعة 2 بعد الظهر مناسب".

بعد ذلك، سنستخدم التخصيصات في 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. الحمولات المخصّصة وبطاقات المحادثة

تتيح الحمولات المخصّصة في Dialogflow إمكانية إرسال رسائل ردّ غنية خاصة بمنصة معيّنة. هذا هو المكان الذي سنضيف فيه بطاقات JSON في Hangouts Chat، حيث سيعرضها الوكيل للمستخدم.

لنبدأ بإضافة بطاقة أساسية لغرض الترحيب. في Dialogflow Console، انتقِل إلى "رسالة الترحيب التلقائية" (Default Welcome Intent) وانتقِل للأسفل إلى قسم الردود.

انقر على Google Chat وأزِل العلامة من المربّع بجانب استخدام الردود من علامة التبويب DEFAULT كأول الردود، ثم انقر على إضافة ردود > حمولة مخصّصة.

سيظهر لك هيكل 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.

بعد ذلك، سنضيف حمولة مخصّصة في رمز التنفيذ حتى نتمكّن من إنشاء المحتوى ديناميكيًا باستخدام الرمز.

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. تتيح لك واجهة برمجة التطبيقات إنشاء صورة "خرائط Google" باستخدام مَعلمات عنوان URL. يمكننا بعد ذلك استخدام الصورة في أداة صورة في بطاقتنا.

1. فعِّل Maps Static API في Google Cloud Console بالطريقة نفسها التي فعّلت بها واجهات برمجة التطبيقات Calendar API وGoogle Chat API.
2. أنشئ مفتاح واجهة برمجة تطبيقات واحفظه لمشروعك في صفحة واجهات برمجة التطبيقات والخدمات في وحدة التحكّم. لمزيد من المعلومات حول استرداد مفاتيح واجهة برمجة التطبيقات وأفضل الممارسات المتعلّقة بها في "خرائط Google"، يُرجى الاطّلاع على هذه الصفحة.
3. انسخ مفتاح واجهة برمجة التطبيقات والثوابت التالية إلى أعلى ملفك في 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 Chat، أنت خبير في Google Workspace.

مزيد من المعلومات

لمزيد من المعلومات، اطّلِع على نماذج الرموز البرمجية في صفحة Dialogflow Github.