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

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

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

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

نافذة الأوامر التي تبدأ بشرطة مائلة
الشكل 1: النافذة التي تظهر عندما يكتب المستخدمون شرطة مائلة في Google Chat

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

الأوامر التي تبدأ بشرطة مائلة مع الردود الخاصة

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

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

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

Node.js

تطبيق Google Chat مفعَّل فيه الميزات التفاعلية لإنشاء تطبيق Chat تفاعلي باستخدام خدمة HTTP، أكمِل عملية البدء السريع هذه.

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

تطبيق Google Chat مفعَّل فيه الميزات التفاعلية لإنشاء تطبيق Chat تفاعلي في Apps Script، أكمِل الخطوات الأساسية هذه.

Python

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat تفاعلي باستخدام خدمة HTTP، أكمِل الخطوات الأساسية هذه.

Java

تطبيق Google Chat مفعَّل فيه الميزات التفاعلية لإنشاء تطبيق Chat تفاعلي باستخدام خدمة HTTP، أكمِل الخطوات الأساسية هذه.

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

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

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

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

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

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

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

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

    • استخدِم كلمات أو عبارات قصيرة ووصفية وقابلة للتنفيذ لجعل الكلمات والتعليمات واضحة وبسيطة للمستخدم. على سبيل المثال، بدلاً من استخدام /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.

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

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

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

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

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

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

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

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

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

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

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

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

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

يعرض الرمز التالي مثالاً على تطبيق في Chat يستجيب للأمر /about من خلال التعامل مع أحداث تفاعل MESSAGE وتحديد ما إذا كانت الرسالة تحتوي على معرّف الأمر المطابق أم لا. إذا كانت الرسالة تحتوي على رقم تعريف الطلب، يعرض تطبيق Chat رسالة خاصة:

Node.js

node/avatar-app/index.js
// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

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

apps-script/avatar-app/avatar-app.gs
// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py
# Checks for the presence of a slash command in the message.
if "slashCommand" in request_json["message"]:
  # Executes the slash command logic based on its ID.
  # Slash command IDs are set in the Google Chat API configuration.
  if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
    return {
      "privateMessageViewer": request_json["user"],
      "text": 'The Avatar app replies to Google Chat messages.'
    }

Java

java/avatar-app/src/main/java/App.java
// Checks for the presence of a slash command in the message.
if (body.getAsJsonObject("message").has("slashCommand")) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
  switch (slashCommand.get("commandId").getAsString()) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
        .setName(body.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
  }
}

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