إنشاء إضافة Google Chat باستخدام Dialogflow ES

توضّح هذه الصفحة كيفية إنشاء تطبيق Google Chat كإضافة Google Workspace تستخدم Dialogflow ES لفهم اللغة الطبيعية والردّ عليها. يمكنك أيضًا استخدام Dialogflow CX، الذي يتكامل مباشرةً مع Google Chat، لإنشاء تطبيق Dialogflow CX Google Chat باتّباع دليل ‫Dialogflow CX Google Chat.

الأهداف

  • إعداد البيئة
  • إنشاء وكيل Dialogflow ES ونشره
  • إنشاء تطبيق في Chat ونشره باستخدام وكيل Dialogflow ES
  • اختبِر تطبيق Chat.

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

الهندسة المعمارية

يوضّح المخطط التالي بنية تطبيق دردشة تم إنشاؤه باستخدام Dialogflow:

بنية تطبيق Chat تم تنفيذه باستخدام Dialogflow

في الرسم البياني السابق، يتضمّن تفاعل المستخدم مع تطبيق Chat من Dialogflow تدفق المعلومات التالي:

  1. يرسل مستخدم رسالة في Chat إلى تطبيق Chat، إما في رسالة مباشرة أو في مساحة Chat.
  2. يتلقّى وكيل Dialogflow الافتراضي، الذي يقع في ، الرسالة ويعالجها لإنشاء رد.
  3. يمكنك اختياريًا استخدام خطاف ويب في Dialogflow، ليتفاعل وكيل Dialogflow مع خدمات خارجية تابعة لجهات خارجية، مثل نظام إدارة المشاريع أو أداة إصدار التذاكر.
  4. يرسل وكيل Dialogflow ردًا إلى خدمة تطبيق Chat في Chat.
  5. يتم تسليم الرد إلى مساحة Chat.

إعداد البيئة

قبل استخدام واجهات Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.

  1. في Google API Console، فعِّل Google Chat API وDialogflow API.

    تفعيل واجهات برمجة التطبيقات

  2. تأكَّد من أنّك بصدد تفعيل واجهات برمجة التطبيقات في مشروع Cloud الصحيح، ثم انقر على التالي.

  3. تأكَّد من تفعيل واجهات برمجة التطبيقات الصحيحة، ثم انقر على تفعيل.

إنشاء وكيل في Dialogflow ES

إذا لم يكن لديك وكيل حالي في Dialogflow ES:

  1. انتقِل إلى وحدة تحكّم Dialogflow ES.
  2. انقر على إنشاء وكيل.
  3. أدخِل اسمًا واختَر لغة تلقائية ومنطقة زمنية.
  4. ربطها بمشروعك على Google Cloud
  5. انقر على إنشاء.
  6. أنشئ النوايا والكيانات حسب الحاجة لسير المحادثة في تطبيق Chat. يمكنك البدء بنية التحية.
  7. دوِّن رقم تعريف المشروع.

للحصول على دليل مفصّل، يُرجى الاطّلاع على إنشاء وكيل.

إنشاء تطبيق Chat وربطه بوكيل Dialogflow

بعد إنشاء وكيل Dialogflow ES، اتّبِع الخطوات التالية لتحويله إلى تطبيق Chat:

  1. في "وحدة تحكّم Google API"، انتقِل إلى Google Chat API. ابحث عن "Google Chat API" وانقر على Google Chat API، ثم انقر على إدارة.

    الانتقال إلى Chat API

  2. انقر على الإعداد وأعِدّ تطبيق Chat على النحو التالي:

    1. في حقل اسم التطبيق، أدخِل Dialogflow App.
    2. في عنوان URL للأفاتار، أدخِل https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png.
    3. في الوصف، أدخِل Responds to real human conversation.
    4. ضمن الوظائف، اختَر الانضمام إلى المساحات والمحادثات الجماعية.
    5. ضمن إعدادات الاتصال، اختَر Dialogflow.
    6. ضمن إعدادات Dialogflow، اختَر Dialogflow ES.
    7. إتاحة تطبيق Chat لمستخدمين ومجموعات محدّدة في نطاقك وأدخِل عنوان بريدك الإلكتروني.
    8. ضمن السجلات، اختَر تسجيل الأخطاء في خدمة تسجيل البيانات.

  3. انقر على حفظ.

تطبيق Chat جاهز لتلقّي الرسائل والردّ عليها.

اختبار تطبيق Chat

اختبِر تطبيق Chat في Dialogflow ES من خلال مراسلته في Google Chat.

  1. افتح Google Chat باستخدام حساب Google Workspace الذي قدّمته عند إضافة نفسك كمختبِر موثوق به.

    الانتقال إلى Google Chat

  2. انقر على محادثة جديدة.
  3. في حقل إضافة مستخدم واحد أو أكثر، اكتب اسم تطبيق Chat.

  4. اختَر تطبيق Chat من النتائج. سيتم فتح رسالة مباشرة.

  5. في الرسالة المباشرة الجديدة مع التطبيق، اكتب Hello واضغط على enter.

    يردّ تطبيق Dialogflow Chat برسالة ترحيب.

الردود النصية

يتم إرسال الردود النصية إلى Google Chat على شكل رسائل نصية. باستخدام هذا التنسيق، يمكنك كتابة النص بخط غامق أو مائل من خلال إحاطة النص برموز معيّنة (Markdown Light).

يبدو الرد على الرسالة النصية مشابهًا تمامًا لـ "الرد التلقائي على الرسائل النصية" في Dialogflow Console. ومع ذلك، ستختلف استجابة واجهة برمجة التطبيقات الأولية بعض الشيء. يضبط هذا الحقل أيضًا إعدادات النظام الأساسي على GOOGLE_HANGOUTS، وهو ما قد يكون مفيدًا عند إنشاء وكلاء لعمليات دمج متعددة.

"fulfillmentMessages": [
{
   "text": {
   "text": [
        "This is a test."
   ]
},
  "platform": "GOOGLE_HANGOUTS"
},

بيانات بطاقات الائتمان

يتم إرسال ردود البطاقات إلى Google Chat على شكل رسائل بطاقات.

الصور

يتم إرسال ردود الصور إلى Google Chat على شكل أدوات صور Google Chat.

الحمولة المخصّصة

لإرسال أنواع أخرى من رسائل Google Chat، يمكنك استخدام حمولة مخصّصة.

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

في ما يلي مثال على حمولة مخصّصة لإنشاء رسالة تتضمّن بطاقة:

{ "hangouts": { "hostAppDataAction": { "chatDataAction": {
  "createMessageAction": { "message": { "cardsV2": [{
    "cardId": "pizza",
    "card": {
      "header": {
        "title": "Pizza Delivery Customer Support",
        "subtitle": "pizzadelivery@example.com",
        "imageUrl": "https://goo.gl/aeDtrS"
      },
      "sections": [{ "widgets": [{ "textParagraph": {
        "text": " Your pizza is here!"
      }}]}]
    }
  }]}}
}}}}

الحدود والاعتبارات

  • عند استخدام إضافات Google Workspace مع Dialogflow، تنطبق القيود والاعتبارات التالية على عناصر أحداث المحادثة:
    • أحداث صفحة "التطبيق" الرئيسية: لا تتوفّر بعد إمكانية استخدام أحداث APP_HOME.
    • إدخال طلب البحث في Dialogflow: يعتمد النص الذي يتم إرساله كإدخال لطلب البحث إلى وكيل Dialogflow على نوع الحدث:
      • MESSAGE: قيمة الحقل argumentText من رسالة المحادثة.
      • APP_COMMAND: السلسلة "APP_COMMAND_PAYLOAD"
      • ADDED_TO_SPACE: يتم إرسال حدث ترحيبي تلقائي.
      • REMOVED_FROM_SPACE: السلسلة "REMOVED_FROM_SPACE_PAYLOAD"
      • CARD_CLICKED: السلسلة "BUTTON_CLICKED_PAYLOAD"
      • WIDGET_UPDATED: السلسلة "WIDGET_UPDATED_PAYLOAD" (المستخدَمة في الإكمال التلقائي)
    • حِمل الحدث الكامل: يتم إرسال حِمل JSON الكامل لحدث التفاعل مع المحادثة إلى Dialogflow ضمن الحقل WebhookRequest.payload. يمكنك الوصول إلى هذه البيانات في Webhook الخاص بخدمة Dialogflow. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات طلبات Webhook في Dialogflow ES.
  • اعتبارات الاستجابة للأوامر وتلقّي البيانات من البطاقات أو مربّعات الحوار:
  • لا تتوفّر معاينات الروابط.
  • إذا ردّ وكيل Dialogflow برسالة واحدة فقط، يتم إرسال الرسالة إلى Google Chat بشكل متزامن. إذا ردّ وكيل Dialogflow بعدة رسائل، يتم إرسال جميع الرسائل إلى Chat بشكل غير متزامن من خلال استدعاء الطريقة create في المورد spaces.messages في Chat API مرة واحدة لكل رسالة.
  • عند استخدام عملية الدمج بين Dialogflow ES وChat، يجب إعداد كلّ من وكيل Dialogflow وتطبيق Chat في مشروع Google Cloud نفسه.

تحديد المشاكل وحلّها

لتصحيح أخطاء تطبيق Chat، ابدأ بمراجعة سجلّات الأخطاء. بما أنّ هذا التطبيق يستخدم Dialogflow، تتوفّر لك العديد من المراجع لتسجيل البيانات وتحديد المشاكل وحلّها:

تَنظيم

لتجنُّب تحمّل رسوم على حسابك مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، ننصحك بحذف مشروع Cloud.

  1. في Google API Console، انتقِل إلى صفحة إدارة الموارد. انقر على القائمة > إدارة الهوية وإمكانية الوصول والمشرف > إدارة الموارد.

    الانتقال إلى "إدارة الموارد"

  2. في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف .
  3. في مربّع الحوار، اكتب معرّف المشروع، ثم انقر على إيقاف لحذف المشروع.
  • ‫Dialogflow CX هي طريقة أخرى لاستخدام Dialogflow مع تطبيق Chat.