الردّ على أوامر تطبيق Google Chat

توضّح هذه الصفحة كيفية إعداد الأوامر والردّ عليها كتطبيق Google Chat.

تساعد الأوامر المستخدمين في استكشاف الميزات الرئيسية لتطبيق Chat واستخدامها، ويمكن لتطبيقات Chat فقط الاطّلاع على محتوى الأمر. على سبيل المثال، إذا أرسل مستخدم رسالة تتضمّن أمرًا يبدأ بشرطة مائلة، لن تظهر الرسالة إلا للمستخدم ولتطبيق Chat.

لتحديد ما إذا كان عليك إنشاء أوامر، وللتعرّف على كيفية تصميم تفاعلات المستخدمين، راجِع تحديد جميع رحلات المستخدمين.

أنواع أوامر تطبيق Chat

يمكنك إنشاء أوامر لتطبيق Chat على شكل أوامر تبدأ بشرطة مائلة أو أوامر سريعة. للاطّلاع على كل نوع من الأوامر واستخدامه، على المستخدمين اتّباع الخطوات التالية:
  1. الأوامر التي تبدأ بشرطة مائلة: يرسل المستخدمون الأوامر كرسائل عن طريق كتابة شرطة مائلة (/) ثم نص محدّد مسبقًا، مثل /about. يمكن أن تطلب تطبيقات المحادثة أيضًا نص وسيط لأمر الشرطة المائلة. على سبيل المثال، قد يتطلّب الأمر /search الذي يبدأ بشرطة مائلة نص وسيطة يُستخدَم في طلب بحث.
  2. الأوامر السريعة: يستخدم المستخدمون الأوامر من خلال فتح القائمة من قسم الرد في رسالة Chat. لاستخدام أحد الأوامر، ينقر المستخدم على إضافة ثم يختار أمرًا من القائمة.
تعرض الصور التالية كيفية عثور المستخدمين على قائمة بالأوامر التي تبدأ بشرطة مائلة والأوامر السريعة:
  • يعثر مستخدم على أوامر تبدأ بشرطة مائلة.
    الشكل 1. يتعرّف المستخدمون على الأوامر التي تبدأ بشرطة مائلة ويستخدمونها من خلال كتابة شرطة مائلة / في حقل الردّ متبوعة باسم الأمر.
  • يعرض المستخدم الأوامر السريعة من القائمة.
    الشكل 2. يمكن للمستخدمين العثور على الأوامر السريعة واستخدامها من القائمة في قسم الرد على رسالة Chat.

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

HTTP

إضافة Google Workspace توسّع نطاق Google Chat. لإنشاء واحد، أكمل دليل البدء السريع الخاص ببروتوكول HTTP.

برمجة تطبيقات

إضافة Google Workspace توسّع نطاق Google Chat. لإنشاء تطبيق، أكمِل دليل البدء السريع في Apps Script.

إعداد الأمر

يوضّح هذا القسم كيفية إكمال الخطوات التالية لإعداد أمر:

  1. أنشئ اسمًا ووصفًا للأمر.
  2. ضبط الأمر في Google Cloud Console

تسمية الأمر ووصفه

اسم الأمر هو ما يكتبه المستخدمون أو يختارونه لتفعيل تطبيق Chat. يظهر أيضًا وصف موجز أسفل الاسم لتوجيه المستخدمين بشكل أكبر بشأن كيفية استخدام الأمر:

اسم الأمر الذي يبدأ بشرطة مائلة ووصفه
الشكل 3: اسم ووصف أمر يبدأ بشرطة مائلة.

عند اختيار اسم ووصف للأمر، ضع في اعتبارك الاقتراحات التالية:

لتسمية أمر:

  • استخدِم كلمات أو عبارات قصيرة وواضحة وقابلة للتنفيذ لجعل الأوامر واضحة للمستخدم. على سبيل المثال، بدلاً من الاسم Create a reminder، استخدِم Remind me.
  • ننصحك باستخدام اسم فريد أو شائع للأمر. إذا كان الأمر يصف تفاعلاً أو ميزة نموذجية، يمكنك استخدام اسم شائع يعرفه المستخدمون ويتوقعونه، مثل Settings أو Feedback. بخلاف ذلك، حاوِل استخدام أسماء أوامر فريدة، لأنّه إذا كان اسم الأمر هو نفسه في تطبيقات Chat الأخرى، على المستخدم فلترة الأوامر المشابهة للعثور على الأمر الخاص بك واستخدامه.

لوصف أمر:

  • احرص على أن يكون الوصف قصيرًا وواضحًا ليعرف المستخدمون ما يمكن توقّعه عند استخدام الأمر.
  • أخبِر المستخدمين إذا كانت هناك أي متطلبات تنسيق للأمر. على سبيل المثال، إذا أنشأت أمرًا يبدأ بشرطة مائلة ويتطلّب نص وسيطة، اضبط الوصف على شيء مثل Remind me to do [something] at [time].
  • أخبِر المستخدمين ما إذا كان تطبيق Chat يرد على الجميع في المساحة أو بشكل خاص على المستخدم الذي يستدعي الأمر. على سبيل المثال، بالنسبة إلى الأمر السريع About، يمكنك وصفه على النحو التالي Learn about this app (Only visible to you).

ضبط الأمر في Google Cloud Console

لإنشاء أمر يبدأ بشرطة مائلة أو أمر سريع، عليك تحديد معلومات حول الأمر في إعدادات تطبيق Chat لواجهة Google Chat API.

لضبط أمر في Google Chat API، أكمل الخطوات التالية: o لضبط أمر شرطة مائلة في Google Chat API، أكمل الخطوات التالية:

  1. في Google Cloud Console، انقر على"القائمة " > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة > Google Chat API.

    الانتقال إلى صفحة Google Chat API

  2. انقر على الإعداد.

  3. ضمن إعدادات الاتصال، انتقِل إلى المشغّلات وحدِّد تفاصيل نقطة النهاية. يجب استخدام هذا المشغّل في القسم التالي للرد على الأمر.

    1. عنوان URL لنقطة نهاية HTTP: يمكنك تحديد عنوان URL واحد مشترك لنقطة نهاية HTTP هنا. بدلاً من ذلك، لاستخدام نقاط نهاية HTTP مختلفة لمشغّلات مختلفة، حدِّد نقطة النهاية مباشرةً في حقل أمر التطبيق.
    2. برمجة التطبيقات: أدخِل رقم تعريف عملية نشر "برمجة التطبيقات". سيتم استدعاء الدالة onAppCommand تلقائيًا. لاستخدام دالة مختلفة من Apps Script، حدِّد اسم الدالة المخصّصة في حقل أمر التطبيق.

  4. ضمن الأوامر، انقر على إضافة أمر.

  5. أدخِل المعلومات التالية حول الأمر:

    1. رقم تعريف الأمر: هو رقم يتراوح بين 1 و1000 يستخدمه تطبيق Chat للتعرّف على الأمر وعرض ردّ.
    2. الوصف: النص الذي يوضّح كيفية استخدام الأمر وتنسيقه يمكن أن يصل عدد الأحرف في الأوصاف إلى 50 حرفًا.
    3. نوع الأمر: اختَر أمر سريع أو أمر الشرطة المائلة.
    4. حدِّد اسمًا للأمر السريع أو الأمر الذي يبدأ بشرطة مائلة:
      • اسم الأمر السريع: هو الاسم المعروض الذي يختاره المستخدمون من القائمة لتنفيذ الأمر. يمكن أن يصل طوله إلى 50 حرفًا وأن يتضمّن أحرفًا خاصة. مثلاً: Remind me
      • اسم الأمر الذي يبدأ بشرطة مائلة: النص الذي يكتبه المستخدمون لتنفيذ الأمر في رسالة. يجب أن يبدأ بشرطة مائلة، وأن يحتوي على نص فقط، ويمكن أن يصل إلى 50 حرفًا. مثلاً: /remindMe

  6. اختياري: إذا أردت أن يردّ تطبيق Chat على الأمر من خلال مربّع حوار، ضَع علامة في مربّع الاختيار فتح مربّع حوار.

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

تم الآن إعداد الأمر لتطبيق Chat.

الردّ على أمر

عندما يستخدم المستخدمون أمرًا، يتلقّى تطبيق Chat عنصر حدث. تحتوي حمولة الحدث على عنصر appCommandPayload يتضمّن تفاصيل حول الأمر الذي تم استدعاؤه (بما في ذلك معرّف الأمر ونوعه)، وذلك لكي تتمكّن من عرض ردّ مناسب. يتم إرسال عنصر الحدث إلى نقطة نهاية HTTP أو دالة Apps Script التي حدّدتها عند ضبط مشغّل أمر التطبيق.

رسالة خاصة لتطبيق Cymbal Labs Chat. تشير الرسالة إلى أنّ تطبيق Chat تم إنشاؤه بواسطة Cymbal Labs وتتضمّن رابطًا إلى المستندات ورابطًا للتواصل مع فريق الدعم.
يردّ تطبيق Chat بشكل خاص على أمر الشرطة المائلة /help لتوضيح كيفية الحصول على الدعم.

يعرض الرمز التالي مثالاً على تطبيق Chat يردّ على الأمر الشرطي /about برسالة نصية. للرد على الأوامر التي تبدأ بشرطة مائلة، يعالج تطبيق Chat عناصر الأحداث من مشغّل أمر التطبيق. عندما تحتوي حمولة كائن حدث على معرّف أمر يتضمّن شرطة مائلة، يعرض تطبيق Chat الإجراء DataActions مع الكائن createMessageAction:

Node.js 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

برمجة تطبيقات 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (appCommandMetadata.appCommandId) {
      case ABOUT_COMMAND_ID:
          return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
              text: 'The Avatar app replies to Google Chat messages.'
          }}}}};
  }
}

لاستخدام نموذج الرمز هذا، استبدِل ABOUT_COMMAND_ID بمعرّف الأمر الذي حدّدته عند إعداد الأمر في Chat API.

اختبار الأمر

لاختبار الأمر والرمز، يُرجى الاطّلاع على المقالة اختبار الميزات التفاعلية لتطبيقات Google Chat.

لمعرفة كيفية اختبار الأمر واستخدامه في واجهة مستخدم Chat، راجِع مقالة استخدام التطبيقات في Google Chat ضمن مستندات "مساعدة Google Chat".