يشرح هذا الدليل طريقة استدعاء واجهة برمجة تطبيقات Google Chat
messages.create()
لإجراء أي مما يلي:
- يمكنك إرسال رسائل تحتوي على نصوص وبطاقات وتطبيقات مصغّرة تفاعلية.
- إرسال الرسائل بشكل خاص إلى مستخدم محدّد في Chat
- بدء سلسلة رسائل أو الرد عليها
- أضِف اسمًا للرسالة ليكون بإمكانك تحديدها في Chat API الأخرى. الطلبات.
الحد الأقصى لحجم الرسالة (بما في ذلك أي نصوص أو بطاقات) هو 32000 بايت. لإرسال رسالة يتجاوز حجمها هذا الحجم، يجب أن يستخدم تطبيق Chat. إرسال رسائل متعددة بدلاً من ذلك.
بالإضافة إلى استدعاء طريقة "messages.create()
"، تطبيقات Chat
إنشاء رسائل وإرسالها للردّ على تفاعلات المستخدمين، مثل نشر
رسالة ترحيب بعد إضافة مستخدم لتطبيق Chat إلى
مساحة. عند الردّ على التفاعلات، يمكن لتطبيقات Chat استخدام سمات
أنواع ميزات المراسلة، بما في ذلك مربّعات الحوار التفاعلية ومعاينة الروابط
من الواجهات. للردّ على مستخدم، يعود تطبيق Chat
الرسالة بشكل متزامن، بدون استدعاء Chat API. للتعلّم
حول إرسال الرسائل للرد على التفاعلات، راجع
تلقّي التفاعلات والردّ عليها باستخدام تطبيق Google Chat
كيفية عرض Chat وسمات الرسائل التي تم إنشاؤها باستخدام Chat API
يمكنك استدعاء الطريقة messages.create()
باستخدام
مصادقة التطبيقات
ومصادقة المستخدم.
تختلف سمات مُرسِل الرسالة في Chat
بناءً على نوع المصادقة التي تستخدمها.
عند إجراء المصادقة داخل تطبيق Chat، يرسل تطبيق Chat الرسالة.
App
بجانب اسمه.عند المصادقة كمستخدم، يرسل تطبيق Chat نيابةً عن المستخدم. ينسب Chat أيضًا تطبيق Chat على الرسالة من خلال عرض الاسم
يحدِّد نوع المصادقة أيضًا ميزات المراسلة وواجهاتها. التي يمكنك تضمينها في الرسالة. من خلال مصادقة التطبيقات، يمكن لتطبيقات Chat إرسال رسائل تحتوي على نصوص منسّقة وواجهات قائمة على البطاقات وأدوات تفاعلية بما أنّه لا يمكن لمستخدمي Chat إرسال رسائل نصية إلا في رسائلهم، يمكنك تضمين النص فقط عند إنشاء الرسائل باستخدام مصادقة المستخدم. لمعرفة المزيد من المعلومات عن المراسلة الميزات المتوفرة في Chat API، يمكنك الاطّلاع على نظرة عامة على رسائل Google Chat
يشرح هذا الدليل كيفية استخدام أيّ من نوعَي المصادقة لإرسال الرسائل. باستخدام Chat API
المتطلبات الأساسية
Node.js
- نشاط تجاري أو مؤسسة حساب Google Workspace لديه إذن بالوصول إلى Google Chat
- إعداد البيئة:
- أنشِئ مشروعًا على Google Cloud.
- ضبط شاشة موافقة OAuth
- تفعيل Google Chat API وضبطه باستخدام اسم ورمزه ووصفه لتطبيق Chat.
- تثبيت Node.js Cloud Client Library.
- إنشاء بيانات اعتماد الوصول استنادًا إلى طريقة المصادقة في Google Chat API
الطلب:
- للمصادقة كمستخدم Chat،
إنشاء معرِّف عميل OAuth
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
client_secrets.json
إلى الدليل المحلي. - للمصادقة كتطبيق Chat، اتّبِع الخطوات التالية:
إنشاء حساب خدمة
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
credentials.json
- للمصادقة كمستخدم Chat،
إنشاء معرِّف عميل OAuth
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
- اختر نطاق تفويض استنادًا إلى ما إذا كنت تريد المصادقة كمستخدم أو تطبيق Chat
- مساحة Google Chat حيث يمكن للمستخدم الذي تمت مصادقته أو الاتصال بتطبيق Chat عضو. للمصادقة بوصفها تطبيق Chat، أضِف تطبيق Chat على المساحة
Python
- نشاط تجاري أو مؤسسة حساب Google Workspace لديه إذن بالوصول إلى Google Chat
- إعداد البيئة:
- أنشِئ مشروعًا على Google Cloud.
- ضبط شاشة موافقة OAuth
- تفعيل Google Chat API وضبطه باستخدام اسم ورمزه ووصفه لتطبيق Chat.
- تثبيت بايثون Cloud Client Library.
- إنشاء بيانات اعتماد الوصول استنادًا إلى طريقة المصادقة في Google Chat API
الطلب:
- للمصادقة كمستخدم Chat،
إنشاء معرِّف عميل OAuth
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
client_secrets.json
إلى الدليل المحلي. - للمصادقة كتطبيق Chat، اتّبِع الخطوات التالية:
إنشاء حساب خدمة
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
credentials.json
- للمصادقة كمستخدم Chat،
إنشاء معرِّف عميل OAuth
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
- اختر نطاق تفويض استنادًا إلى ما إذا كنت تريد المصادقة كمستخدم أو تطبيق Chat
- مساحة Google Chat حيث يمكن للمستخدم الذي تمت مصادقته أو الاتصال بتطبيق Chat عضو. للمصادقة بوصفها تطبيق Chat، أضِف تطبيق Chat على المساحة
Java
- نشاط تجاري أو مؤسسة حساب Google Workspace لديه إذن بالوصول إلى Google Chat
- إعداد البيئة:
- أنشِئ مشروعًا على Google Cloud.
- ضبط شاشة موافقة OAuth
- تفعيل Google Chat API وضبطه باستخدام اسم ورمزه ووصفه لتطبيق Chat.
- تثبيت Java Cloud Client Library.
- إنشاء بيانات اعتماد الوصول استنادًا إلى طريقة المصادقة في Google Chat API
الطلب:
- للمصادقة كمستخدم Chat،
إنشاء معرِّف عميل OAuth
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
client_secrets.json
إلى الدليل المحلي. - للمصادقة كتطبيق Chat، اتّبِع الخطوات التالية:
إنشاء حساب خدمة
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
credentials.json
- للمصادقة كمستخدم Chat،
إنشاء معرِّف عميل OAuth
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
- اختر نطاق تفويض استنادًا إلى ما إذا كنت تريد المصادقة كمستخدم أو تطبيق Chat
- مساحة Google Chat حيث يمكن للمستخدم الذي تمت مصادقته أو الاتصال بتطبيق Chat عضو. للمصادقة بوصفها تطبيق Chat، أضِف تطبيق Chat على المساحة
برمجة تطبيقات
- نشاط تجاري أو مؤسسة حساب Google Workspace لديه إذن بالوصول إلى Google Chat
- إعداد البيئة:
- أنشِئ مشروعًا على Google Cloud.
- ضبط شاشة موافقة OAuth
- تفعيل Google Chat API وضبطه باستخدام اسم ورمزه ووصفه لتطبيق Chat.
- إنشاء مشروع "برمجة تطبيقات Google" مستقل وفعِّل خدمة المحادثة المتقدّمة.
- في هذا الدليل، يجب عليك استخدام أي من أو مصادقة التطبيقات للمصادقة بصفتك تطبيق Chat، أنشئ بيانات اعتماد حساب الخدمة. لمعرفة الخطوات، يُرجى الاطّلاع على المصادقة والتفويض تطبيق Google Chat
- اختر نطاق تفويض استنادًا إلى ما إذا كنت تريد المصادقة كمستخدم أو تطبيق Chat
- مساحة Google Chat حيث يمكن للمستخدم الذي تمت مصادقته أو الاتصال بتطبيق Chat عضو. للمصادقة بوصفها تطبيق Chat، أضِف تطبيق Chat على المساحة
إرسال رسالة باسم تطبيق Chat
يوضح هذا القسم كيفية إرسال الرسائل التي تحتوي على نصوص وبطاقات تطبيقات مصغّرة تفاعلية باستخدام مصادقة التطبيقات.
لطلب "messages.create()
" باستخدام مصادقة التطبيقات، يجب تحديد
الحقول التالية في الطلب:
- نطاق التفويض في
chat.bot
- مرجع
Space
الذي تريد نشر الرسالة. يجب أن يكون تطبيق Chat: عضوًا في المساحة. Message
مورد يمكن إنشاؤه. لتحديد محتوى الرسالة، يمكنك تضمين نص منسق (text
), واجهة بطاقة واحدة أو أكثر (cardsV2
), أو كليهما.
يمكنك تضمين ما يلي اختياريًا:
- الحقل
accessoryWidgets
المطلوب تضمينه الأزرار التفاعلية في أسفل الرسالة. - يتيح الحقل
privateMessageViewer
إرسال الرسالة بشكل خاص إلى مستخدم محدد. - الحقل
messageId
، الذي يتيح لك يمكنك تسمية الرسالة لاستخدامها في طلبات واجهة برمجة التطبيقات الأخرى. - الحقلان
thread.threadKey
وmessageReplyOption
من أجل بدء سلسلة محادثات أو الرد عليها إذا لم تكن المساحة استخدام سلاسل المحادثات، يتم تجاهل هذا الحقل.
يوضّح الرمز التالي مثالاً على طريقة استخدام تطبيق Chat يمكنه إرسال رسالة منشورة كتطبيق Chat تحتوي على نص وبطاقة وزر قابل للنقر في أسفل الرسالة:
Node.js
Python
Java
برمجة تطبيقات
لتنفيذ هذا النموذج، استبدِل SPACE_NAME
برقم التعريف من
المساحة الإعلانية
name
.
ويمكنك الحصول على المعرّف من خلال استدعاء
طريقة spaces.list()
أو من عنوان URL الخاص بالمساحة.
إضافة تطبيقات مصغّرة تفاعلية في أسفل الرسالة
في عينة التعليمات البرمجية الأولى من هذا الدليل، تعرض رسالة تطبيق Chat زرًا قابلاً للنقر في أسفل الرسالة، وتُعرف باسم أداة الملحقات. تطبيقات مصغّرة للإكسسوار تظهر بعد أي نص أو بطاقات في الرسالة. يمكنك استخدام هذه التطبيقات المصغّرة لطلب المستخدمين بالتفاعل مع رسالتك بعدة طرق، منها ما يلي:
- قيِّم دقة رسالة أو مدى رضاها.
- يمكنك الإبلاغ عن مشكلة في الرسالة أو تطبيق Chat.
- افتح رابطًا يؤدي إلى محتوى ذي صلة، مثل المستندات.
- رفض الرسائل المشابهة أو تأجيلها من تطبيق Chat لفترة زمنية محددة.
لإضافة تطبيقات مصغّرة للملحقات، يجب تضمين
accessoryWidgets[]
في نص طلبك وحدد التطبيق المصغَّر الذي تريده
لتضمينها.
تعرض الصورة التالية تطبيق Chat ملحقًا به. رسالة نصية تحتوي على التطبيقات المصغّرة للملحقات كي يتمكّن المستخدمون من تقييم تجربتهم باستخدام تطبيق Chat.
![التطبيق المصغّر للملحق](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=2&hl=ar)
يوضح ما يلي نص الطلب الذي يؤدي إلى إنشاء رسالة نصية تحتوي على
زرين للملحقات. عندما ينقر المستخدم على زر ما، فإن
(مثل doUpvote
) تعالج التفاعل:
{
text: "Rate your experience with this Chat app.",
accessoryWidgets: [{ buttonList: { buttons: [{
icon: { material_icon: {
name: "thumb_up"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doUpvote"
}}
}, {
icon: { material_icon: {
name: "thumb_down"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doDownvote"
}}
}]}}]
}
إرسال رسالة بخصوصية تامة
يمكن لتطبيقات Chat إرسال الرسائل بخصوصية تامة من أجل لا تظهر هذه الرسالة إلا لمستخدم محدّد في المساحة. عندما تطبيق Chat يرسل رسالة خاصة تصنيفًا يُعلم المستخدم بأن الرسالة مرئية له فقط.
لإرسال رسالة خاصة باستخدام Chat API، حدِّد
privateMessageViewer
في نص طلبك. لتحديد المستخدم، يمكنك ضبط القيمة على
مورد User
الذي
يمثل مستخدم Chat. يمكنك أيضًا استخدام صفحة
الحقل name
من
مورد User
، كما هو موضح في المثال التالي:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
لاستخدام هذا النموذج، استبدِل USER_ID
مع معرّف فريد للمستخدم، مثل 12345678987654321
أو
hao@cymbalgroup.com
لمزيد من المعلومات عن تحديد المستخدمين، راجع
تحديد مستخدمي Google Chat وتحديدهم
لإرسال رسالة خاصة، يجب حذف ما يلي في طلبك:
إرسال رسالة نصية نيابةً عن مستخدم
يوضح هذا القسم كيفية إرسال الرسائل نيابةً عن مستخدم باستخدام مصادقة المستخدم. من خلال مصادقة المستخدم، يمكن أن يتضمّن محتوى الرسالة نصًا فقط. ويجب أن يغفل ميزات المراسلة التي تتوفر فقط تطبيقات Chat، بما في ذلك واجهات البطاقات والتطبيقات المصغّرة التفاعلية
لطلب رقم messages.create()
باستخدام مصادقة المستخدم، يجب تحديد
الحقول التالية في الطلب:
- نطاق التفويض
يتيح إمكانية مصادقة المستخدم لهذه الطريقة. تشمل الاستخدامات التالية
النطاق
chat.messages.create
. - مرجع
Space
الذي تريد نشر الرسالة. يجب أن يكون المستخدم الذي تمت مصادقته عضوًا في مساحة. Message
مورد يمكن إنشاؤه. لتحديد محتوى الرسالة، يجب عليك تضمينtext
.
يمكنك تضمين ما يلي اختياريًا:
- الحقل
messageId
، الذي يتيح لك يمكنك تسمية الرسالة لاستخدامها في طلبات واجهة برمجة التطبيقات الأخرى. - الحقلان
thread.threadKey
وmessageReplyOption
من أجل بدء سلسلة محادثات أو الرد عليها إذا لم تكن المساحة استخدام سلاسل المحادثات، يتم تجاهل هذا الحقل.
يوضّح الرمز التالي مثالاً على طريقة استخدام تطبيق Chat إرسال رسالة نصية في مساحة معيّنة نيابةً عن مستخدم تمت مصادقته:
Node.js
Python
Java
برمجة تطبيقات
لتنفيذ هذا النموذج، استبدِل SPACE_NAME
برقم التعريف من
المساحة الإعلانية
name
. ويمكنك الحصول على المعرّف من خلال استدعاء
طريقة spaces.list()
أو من عنوان URL الخاص بالمساحة.
بدء سلسلة محادثات أو الرد عليها
بالنسبة إلى المساحات التي تستخدم سلاسل المحادثات، عليك اتّباع الخطوات التالية: يمكنك تحديد ما إذا كانت رسالة جديدة تبدأ سلسلة محادثات أو ردودًا سلسلة محادثات حالية.
تبدأ الرسائل التي تنشئها باستخدام Chat API تلقائيًا . لمساعدتك في تحديد سلسلة المحادثات والرد عليها لاحقًا، يمكنك تحديد مفتاح سلسلة المحادثات في طلبك:
- في نص طلبك، حدد
thread.threadKey
. - تحديد معلَمة طلب البحث
messageReplyOption
لتحديد ما سيحدث إذا كان المفتاح موجودًا بالفعل.
لإنشاء رسالة يتم الردّ عليها على سلسلة محادثات حالية:
- يُرجى تضمين الحقل
thread
في نص طلبك. في حال ضبطها، يمكنك تحديدthreadKey
التي قمت بإنشائها. بخلاف ذلك، يجب عليك استخدامname
سلسلة المحادثات. - حدِّد معلَمة طلب البحث
messageReplyOption
.
يوضّح الرمز التالي مثالاً على طريقة استخدام تطبيق Chat يمكنه إرسال رسالة نصية تبدأ أو يرد على سلسلة محادثات معينة يتم تحديدها بواسطة مفتاح مساحة معيّنة نيابةً عن مستخدم تمت مصادقته:
Node.js
Python
Java
برمجة تطبيقات
لتشغيل هذا النموذج، استبدل ما يلي:
THREAD_KEY
: مفتاح سلسلة محادثات حالي في المساحة لإنشاء سلسلة محادثات جديدة، واسم فريد لسلسلة المحادثات.SPACE_NAME
: رقم التعريف الوارد في المساحةname
. ويمكنك الحصول على المعرّف من خلال استدعاء طريقةspaces.list()
أو من عنوان URL الخاص بالمساحة.
تسمية رسالة
لاسترداد رسالة أو تحديدها في طلبات البيانات من واجهة برمجة التطبيقات المستقبلية، يمكنك تسمية رسالة.
من خلال إعداد الحقل messageId
في طلب messages.create()
.
تتيح لك تسمية رسالتك تحديد الرسالة بدون الحاجة إلى تخزين
الذي يعيّنه النظام من اسم مورد الرسالة (يتم تمثيله في
name
).
فعلى سبيل المثال، لاسترداد رسالة باستخدام الطريقة get()
، يمكنك استخدام طريقة
اسم المورد لتحديد الرسالة التي يجب استردادها. اسم المورد هو
بتنسيق spaces/{space}/messages/{message}
، حيث يمثل {message}
المعرّف الذي عيّنه النظام أو الاسم المخصّص الذي حدّدته عند إنشاء
.
لتسمية رسالة، حدِّد معرّفًا مخصّصًا في
messageId
عند إنشاء الرسالة. يضبط الحقل messageId
قيمة السمة
clientAssignedMessageId
في المورد Message
.
لا يمكنك تسمية رسالة إلا عند إنشائها. لا يمكنك تسمية أو تعديل مُعرّف مخصّص للرسائل الحالية. يجب أن يستوفي المعرّف المخصّص ما يلي: المتطلبات:
- يبدأ بـ
client-
. على سبيل المثال،client-custom-name
هو نطاق مخصص صالح. المعرّف، ولكنcustom-name
ليس كذلك. - يحتوي على ما يصل إلى 63 حرفًا وأحرف صغيرة وأرقام واصلات.
- أن تكون فريدة داخل مساحة لا يمكن لتطبيق Chat استخدام المعرّف المخصص نفسه لرسائل مختلفة.
يوضّح الرمز التالي مثالاً على طريقة استخدام تطبيق Chat إرسال رسالة نصية تتضمن معرّفًا إلى مساحة معينة نيابةً عن مستخدم تمت مصادقته:
Node.js
Python
Java
برمجة تطبيقات
لتشغيل هذا النموذج، استبدل ما يلي:
SPACE_NAME
: رقم التعريف الوارد في المساحةname
. ويمكنك الحصول على المعرّف من خلال استدعاء طريقةspaces.list()
أو من عنوان URL الخاص بالمساحة.MESSAGE-ID
: اسم للرسالة التي تبدأ معcustom-
. يجب أن يكون فريدًا عن أي أسماء رسائل أخرى تم إنشاؤها بواسطة تطبيق Chat في المساحة المحدّدة
تحديد المشاكل وحلّها
عند تثبيت تطبيق Google Chat أو تعرض card خطأً، تعرض واجهة Chat رسالة مفادها "حدث خطأ". أو "تعذَّرت معالجة طلبك". في بعض الأحيان، لا يمكن واجهة مستخدم Chat لا يعرض أي رسالة خطأ، ولكن يظهر تطبيق Chat أو ينتج عن بطاقة نتيجة غير متوقعة؛ على سبيل المثال، قد لا تظهر رسالة البطاقة موضع الإعلان.
على الرغم من أنه قد لا تظهر رسالة الخطأ في واجهة مستخدم Chat، تتوفر رسائل خطأ وصفية وبيانات السجل لمساعدتك في إصلاح الأخطاء عند تفعيل ميزة تسجيل الأخطاء لتطبيقات Chat للحصول على مساعدة في العرض، وتصحيح الأخطاء وإصلاح الأخطاء، فراجع تحديد مشاكل Google Chat وحلّها.
مواضيع ذات صلة
- استخدام "أداة إنشاء البطاقات" من أجل تصميم رسائل بطاقة JSON ومعاينتها لتطبيقات Chat.
- تنسيق الرسائل:
- الحصول على تفاصيل حول رسالة
- إدراج الرسائل في مساحة
- تعديل رسالة
- حذف رسالة
- تحديد المستخدمين في رسائل Google Chat
- إرسال الرسائل إلى Google Chat باستخدام الردود التلقائية الواردة على الويب