إرسال رسائل خاصة إلى مستخدمي Google Chat

تشرح هذه الصفحة كيفية إنشاء رسائل خاصة وإرسالها تطبيق Google Chat

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

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

عند إرسال أحد تطبيقات Chat رسالة خاصة، ستُرسَل الرسالة تصنيفًا يُعلم المستخدم بأن الرسالة مرئية له فقط:

رسالة خاصة إلى تطبيق Cymbal Labs في Chat. تقول الرسالة أن تم إنشاء تطبيق Chat بواسطة Cymbal Labs وهو يشارك رابطًا. إلى الوثائق ورابط للتواصل مع فريق الدعم.
الشكل 1: عندما يرسل أحد تطبيقات Chat رسالة خاصة، يرى المستخدم رسالة تحمل تصنيفًا نص الرسالة هو Only visible to you.

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

Node.js

Python

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

إرسال رسالة خاصة

لإرسال رسالة خاصة كتطبيق Chat، عليك تحديد الـ privateMessageViewer في الرسالة عند إنشائها. يمكنك إنشاء رسائل خاصة تمامًا يمكنك إنشاء أي رسالة: إما عن طريق الرد على تفاعل المستخدم، أو بشكل غير متزامن create() على صفحة مرجع Message لمعرفة خطوات إرسال رسائل نصية أو رسائل، راجع إرسال رسالة

يوضح المثال التالي ملف JSON لرسالة نصية خاصة مفادها Hello private world!:

{
    "text": "Hello private world!",
    "privateMessageViewer": "USER"
}

في هذا المثال، يمثل USER مستخدم Chat الذين يمكنهم عرض الرسالة، بتنسيق User المرجع. في حال الاستجابة تفاعل المستخدم، يمكنك تحديد كائن User من حدث التفاعل. على سبيل المثال، راجِع القسم التالي. الرد بشكل خاص على أمر يبدأ بشرطة مائلة.

أما إذا أردت تحديد مُشاهد للرسالة الخاصة، فيمكنك استخدام الحقل name من User المصدر:

{
    "text": "Hello private world!",
    "privateMessageViewer": {
      "name": "users/USER_ID"
    }
}

في هذا المثال، يمكنك استخدام الحقل name لتحديد User الخاصة بالمُشاهد. اسم المورد في Google Chat. استبدال "USER_ID" مع معرّف فريد للمستخدم، مثل 12345678987654321 أو hao@cymbalgroup.com

لمزيد من المعلومات عن تحديد المستخدمين، راجع تحديد مستخدمي Google Chat وتحديدهم

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

يعرض الرمز التالي مثالاً على تطبيق في Chat. تستجيب للأمر الذي يبدأ بشرطة مائلة برسالة خاصة.

يعالج تطبيق Chat حدث تفاعل واحد (MESSAGE) ويرد على الأمر الشرطة المائلة /help برسالة نصية خاصة كيفية استخدامها:

Node.js 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used in Google Chat app.');
  }

  const event = req.body;

  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/help", responds with a private text message.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case '1':  // /help
        return res.json({
          privateMessageViewer: event.user,
          text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
        });
    }
  }

  // If the Chat app doesn't detect a slash command, it responds
  // with a private text message
  return res.json({
    privateMessageViewer: event.user,
    text: 'Try a slash command.'
  });
};

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

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1: // Responds to /help
        return {
          "privateMessageViewer": event.user,
          "text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
        };
    }
  }
  else {
    return { "text": "Try a slash command.", "privateMessageViewer": event.user };
  }
}

Python 

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  if req.method == 'GET':
    return 'Hello! This function must be called from Google Chat.'

  request = req.get_json(silent=True)

  # Checks for the presence of event.message.slashCommand.
  # If the slash command is "/help", responds with a private text message.
  if request.get('message', {}).get('slashCommand'):
    command_id = request.get('message', {}).get('slashCommand').get('commandId')
    if command_id == '1':  # /help
      return {
          'privateMessageViewer': request.get('user'),
          'text': (
              'This Chat app was created by Cymbal Labs. To get help with this'
              ' app, <https://cymbalgroup.com/docs|see our documentation> or'
              ' <https://cymbalgroup.com/support|contact our support team>.'
          ),
      }

  return {
      'privateMessageViewer': request.get('user'),
      'text': 'Try a slash command.',
  }

القيود

لإرسال رسالة خاصة، لا يمكن أن تحتوي الرسالة على الزر التالي:

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

تعديل الرسائل الخاصة أو حذفها

لتعديل رسائل Google Chat أو حذفها، عليك الاتصال بـ واجهة برمجة التطبيقات Chat لا يمكنك تغيير مُشاهد الرسالة الخاصة أو الرسالة متاحة للجميع. لذلك، عند تحديث الرسائل الخاصة، يجب حذف الحقل privateMessageViewer في طلب بيانات من واجهة برمجة التطبيقات (الحقل هو إخراج فقط).

لتعديل رسالة خاصة، راجِع تعديل رسالة لحذف رسالة خاصة، راجع حذف رسالة