الردّ على الأوامر التي تبدأ بشرطة مائلة كتطبيق 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، أكمِل الخطوات الأساسية هذه.

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

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

  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 API

لضبط أمر شرطة مائلة في 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 تحتوي على أمر شرطة مائلة، يتلقّى تطبيقك على Chat حدث تفاعل واحد (MESSAGE). تحتوي حمولة الحدث على slashCommand وslashCommandMetadata الأخرى. تحتوي هذه العناصر على تفاصيل حول الأمر المستخدَم في الرسالة. (بما في ذلك مُعرّف الأمر)، بحيث يمكنك عرض رد مناسب.

رسالة خاصة إلى
  تطبيق Cymbal Labs في Chat. تقول الرسالة أن
  تم إنشاء تطبيق 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:
    JsonObject aboutMessage = new JsonObject();
    aboutMessage.addProperty("text", "The Avatar app replies to Google Chat messages.");
    aboutMessage.add("privateMessageViewer", body.getAsJsonObject("user"));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
  }
}

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