توضّح هذه الصفحة كيفية إنشاء رسائل خاصة وإرسالها في تطبيق Google Chat.
الرسالة الخاصة هي رسالة في تطبيق Chat لا تظهر إلا لمستخدم Chat محدّد. يمكنك استخدام الرسائل الخاصة في المساحات مع عدة أشخاص ليتمكنوا من التفاعل بشكل خاص مع تطبيقات Chat. على سبيل المثال، يمكن لتطبيق Chat إرسال الرسائل بشكل خاص لتنفيذ أي مما يلي:
- الردّ على أمر شرطة مائلة. على سبيل المثال، إذا استدعى أحد المستخدمين الأمر
/about
الذي يبدأ بشرطة مائلة في تطبيق Chat في مساحة، يمكن أن يردّ تطبيق Chat برسالة خاصة توضّح وظيفة تطبيق Chat وكيفية استخدامه. - يمكنك إعلام أو إرسال معلومات ذات صلة بمستخدم واحد فقط. على سبيل المثال، يمكنك إبلاغ المستخدم بأنّه قد تم تكليفه بمهمة، أو تذكيره بإكمال المهمة.
- أرسل رسالة خطأ. على سبيل المثال، إذا حذف المستخدم نص الوسيطة المطلوب للأمر الذي تبدأ بشرطة مائلة، يمكن لتطبيق Chat إرسال رسالة خاصة لتوضيح الخطأ ومساعدة المستخدم في تنسيقه.
عندما يرسل تطبيق في Chat رسالة خاصة، تعرض الرسالة تصنيفًا لإعلام المستخدم بأنّ الرسالة مرئية له فقط:
المتطلبات الأساسية
Node.js
- مشروع على Google Cloud تم فيه تفعيل Google Chat API وضبطه لمعرفة الخطوات، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat.
- للاستجابة بشكل خاص لأمر يستخدم الشرطة المائلة، يتم ضبط أمر يبدأ بشرطة مائلة لتطبيق Chat. ولإنشاء أحد هذه الأوامر، يُرجى مراجعة الاستجابة للأوامر التي تبدأ بشرطة مائلة.
- لإرسال رسالة خاصة باستخدام طريقة
messages.create()
، عليك استخدام مصادقة التطبيقات.
ملاحظة: تمت كتابة نماذج رمز Node.js في هذا الدليل لتشغيلها كدالة Google Cloud.
Python
- مشروع على Google Cloud تم فيه تفعيل Google Chat API وضبطه لمعرفة الخطوات، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat.
- للاستجابة بشكل خاص لأمر يستخدم الشرطة المائلة، يتم ضبط أمر يبدأ بشرطة مائلة لتطبيق Chat. ولإنشاء أحد هذه الأوامر، يُرجى مراجعة الاستجابة للأوامر التي تبدأ بشرطة مائلة.
- لإرسال رسالة خاصة باستخدام طريقة
messages.create()
، عليك استخدام مصادقة التطبيقات.
ملاحظة: تمت كتابة نماذج التعليمات البرمجية Python في هذا الدليل للتشغيل بصفتها دالة Google Cloud باستخدام Python 3.10.
برمجة تطبيقات
- تطبيق في Chat. لإنشاء تطبيق في Chat، يمكنك اتّباع مقالة quickstart هذه.
- للاستجابة بشكل خاص لأمر يستخدم الشرطة المائلة، يتم ضبط أمر يبدأ بشرطة مائلة لتطبيق Chat. ولإنشاء أحد هذه الأوامر، يُرجى مراجعة الاستجابة للأوامر التي تبدأ بشرطة مائلة.
- لإرسال رسالة خاصة باستخدام طريقة
messages.create()
، عليك استخدام مصادقة التطبيقات.
إرسال رسالة خاصة
لإرسال رسالة خاصة كتطبيق Chat، عليك تحديد
الحقل
privateMessageViewer
في الرسالة عند إنشائها. يمكنك إنشاء رسائل خاصة تمامًا كما تنشئ أي رسالة، إمّا من خلال الردّ على تفاعل أحد المستخدمين، أو استدعاء طريقة create()
Google Chat API بشكل غير متزامن على مورد 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 API. لا يمكنك تغيير عارض الرسالة الخاصة أو جعل
الرسالة عامة. وبالتالي، عند تعديل الرسائل الخاصة، عليك حذف
الحقل privateMessageViewer
في طلب البيانات من واجهة برمجة التطبيقات (الحقل هو إخراج فقط).
لتعديل رسالة خاصة، راجِع تعديل رسالة. لحذف رسالة خاصة، راجِع حذف رسالة.
مواضيع ذات صلة
- إرسال رسالة
- تحديد مستخدمي Google Chat وتحديدهم
- الردّ على الأوامر التي تبدأ بشرطة مائلة
- تعديل رسالة
- حذف رسالة