الردّ على الأوامر التي تبدأ بشَرطة مائلة في Google Chat

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

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

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

كيفية استخدام المستخدمين للأوامر التي تبدأ بشرطة مائلة

لاستخدام أمر يبدأ بشرطة مائلة، يكتب المستخدمون شرطة مائلة (/) ثم أمرًا نصيًا قصيرًا، مثل /about للحصول على معلومات عن تطبيق Chat. يمكن للمستخدمين اكتشاف الأوامر التي تبدأ بشرطة مائلة من خلال كتابة شرطة مائلة في Google Chat، ما يؤدي إلى عرض نافذة تسرد الأوامر المتاحة لتطبيق Chat:

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

على سبيل المثال، للاطّلاع على معلومات عن تطبيق Chat الذي يكتشفونه في مساحة، يمكن للمستخدمين استخدام طلبات مثل /about أو /help. لتجنّب إرسال إشعار إلى جميع المستخدمين الآخرين في المساحة، يمكن لتطبيق Chat الردّ بشكل خاص مع تقديم معلومات عن كيفية استخدام تطبيق Chat والحصول على الدعم.

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

إعداد أمر يبدأ بشرطة مائلة

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

1. أنشئ اسمًا لأمر الشرطة المائلة.
2. ضبط الأمر "شرطة مائلة" في Google Chat API

أدخِل اسمًا للأمر الذي يبدأ بشرطة مائلة.

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

عند اختيار اسم ووصف لأمر الشرطة المائلة، ننصحك باتّباع الخطوات التالية:

• لتسمية أمر يبدأ بشرطة مائلة:

  • استخدِم كلمات أو عبارات قصيرة ووصفية وقابلة للتنفيذ لجعل الكلمات والتعليمات واضحة وبسيطة للمستخدم. على سبيل المثال، بدلاً من قول /createAReminder، استخدِم /remindMe.
  • إذا كان الأمر يحتوي على أكثر من كلمة واحدة، يمكنك مساعدة المستخدمين في قراءة الأمر من خلال استخدام الأحرف الصغيرة فقط في الكلمة الأولى ثم كتابة الحرف الأول من الكلمات الإضافية بحرف كبير. على سبيل المثال، بدلاً من /updatecontact، استخدِم /updateContact.
  • ننصحك بالتفكير في استخدام اسم فريد أو شائع لأمرك. إذا كان الأمر يصف تفاعلًا أو ميزة نموذجية، يمكنك استخدام اسم شائع يتعرّف عليه المستخدمون ويتوقعونه، مثل /settingsأو /feedback. بخلاف ذلك، حاوِل استخدام أسماء أوامر فريدة، لأنّه إذا كان اسم العبارة هو نفسه في تطبيقات Chat الأخرى، على المستخدم التمرير بين الأوامر المشابهة للعثور على طلبك واستخدامه.

• لوصف الأمر الذي يبدأ بشرطة مائلة:

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

ضبط الأمر المكوّن من الشرطة المائلة في Google Chat API

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

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

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

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

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

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

4. ضمن الأوامر التي تبدأ بشرطة مائلة، انقر على إضافة أمر يبدأ بشرطة مائلة.

5. أدخِل اسمًا ورقم تعريف للطلب ووصفًا للطلب:

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

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

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

تم الآن ضبط الأمر الذي يبدأ بشرطة مائلة لتطبيق Chat.

الردّ على أمر يبدأ بشرطة مائلة

عندما ينشئ المستخدمون رسالة Chat، يتلقّى تطبيق Chat عنصر حدث يحتوي على معلومات عن الرسالة. يحتوي عنصر الحدث على بيانات أساسية تتضمّن تفاصيل عن الأمر المستخدَم في الرسالة (بما في ذلك رقم تعريف الأمر)، لكي تتمكّن من عرض استجابة مناسبة.

للردّ على أمر يبدأ بشرطة مائلة، عليك تنفيذ العامل المشغِّل الرسالة كي تتمكّن من معالجة أي عناصر حدث تحتوي على بيانات وصفية لأمر يبدأ بشرطة مائلة.

يعرض الرمز البرمجي التالي مثالاً لتطبيق 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 messages 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 chatMessage = req.body.chat.messagePayload.message;

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

    // 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;

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

    // 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 }
                    }]
                }]
            }
        }]
    }}}}};
}

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