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

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

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

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

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

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

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

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

إعداد الطلب

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

  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"

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

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

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

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

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

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

  4. ضمن الطلبات، انقر على إضافة طلب.

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

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

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

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

تم الآن ضبط الأمر لتطبيق Chat.

الردّ على أمر

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

رسالة خاصة لتطبيق Chat من Cymbal Labs. توضّح الرسالة أنّه تم إنشاء تطبيق 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.