يشرح هذا الدليل طريقة استدعاء واجهة برمجة تطبيقات Google Chat
messages.create()
لإجراء أي مما يلي:
- يمكنك إرسال رسائل تحتوي على نصوص وبطاقات وتطبيقات مصغّرة تفاعلية.
- إرسال الرسائل بشكل خاص إلى مستخدم محدّد في Chat
- بدء سلسلة رسائل أو الرد عليها
- أضِف اسمًا للرسالة ليكون بإمكانك تحديدها في Chat API الأخرى. الطلبات.
بالإضافة إلى استدعاء طريقة "messages.create()
"، تطبيقات Chat
إنشاء رسائل وإرسالها للردّ على تفاعلات المستخدمين، مثل نشر
رسالة ترحيب بعد إضافة مستخدم لتطبيق Chat إلى
مساحة. عند الردّ على التفاعلات، يمكن لتطبيقات Chat استخدام سمات
أنواع ميزات المراسلة، بما في ذلك مربّعات الحوار التفاعلية ومعاينة الروابط
من الواجهات. للردّ على مستخدم، يعود تطبيق Chat
الرسالة بشكل متزامن، بدون استدعاء Chat API. للتعلّم
حول إرسال الرسائل للرد على التفاعلات، راجع
تلقّي التفاعلات والردّ عليها باستخدام تطبيق Google Chat
كيفية عرض Chat وسمات الرسائل التي تم إنشاؤها باستخدام Chat API
يمكنك استدعاء الطريقة messages.create()
باستخدام
مصادقة التطبيقات
ومصادقة المستخدم.
تختلف سمات مُرسِل الرسالة في Chat
بناءً على نوع المصادقة التي تستخدمها.
عند إجراء المصادقة داخل تطبيق Chat، يرسل تطبيق Chat الرسالة.
عند المصادقة كمستخدم، يرسل تطبيق Chat نيابةً عن المستخدم. ينسب Chat أيضًا تطبيق Chat على الرسالة من خلال عرض الاسم
يحدِّد نوع المصادقة أيضًا ميزات المراسلة وواجهاتها. التي يمكنك تضمينها في الرسالة. من خلال مصادقة التطبيقات، يمكن لتطبيقات Chat إرسال رسائل تحتوي على نصوص منسّقة وواجهات قائمة على البطاقات وأدوات تفاعلية بما أنّه لا يمكن لمستخدمي Chat إرسال رسائل نصية إلا في رسائلهم، يمكنك تضمين النص فقط عند إنشاء الرسائل باستخدام مصادقة المستخدم. لمعرفة المزيد من المعلومات عن المراسلة الميزات المتوفرة في Chat API، يمكنك الاطّلاع على نظرة عامة على رسائل Google Chat
يشرح هذا الدليل كيفية استخدام أيّ من نوعَي المصادقة لإرسال الرسائل. باستخدام Chat API
المتطلبات الأساسية
Python
- نشاط تجاري أو مؤسسة حساب Google Workspace لديه إذن بالوصول إلى Google Chat
- Python 3.6 أو أعلى
- أداة إدارة حزم pip
- أحدث مكتبات عملاء Google. لتثبيت التطبيقات أو تحديثها،
قم بتشغيل الأمر التالي في واجهة سطر الأوامر:
pip3 install --upgrade google-api-python-client google-auth-oauthlib
- إعداد البيئة:
- أنشِئ مشروعًا على Google Cloud.
- ضبط شاشة موافقة OAuth
- تفعيل Google Chat API وضبطه باستخدام اسم ورمزه ووصفه لتطبيق Chat.
- إنشاء بيانات اعتماد الوصول استنادًا إلى طريقة المصادقة في Google Chat API
الطلب:
- للمصادقة كمستخدم Chat،
إنشاء معرِّف عميل OAuth
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
client_secrets.json
إلى الدليل المحلي. - للمصادقة كتطبيق Chat، اتّبِع الخطوات التالية:
إنشاء حساب خدمة
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
credentials.json
- للمصادقة كمستخدم Chat،
إنشاء معرِّف عميل OAuth
بيانات الاعتماد وحفظ بيانات الاعتماد كملف JSON
- اختر نطاق تفويض استنادًا إلى ما إذا كنت تريد المصادقة كمستخدم أو تطبيق Chat
- مساحة Google Chat حيث يمكن للمستخدم الذي تمت مصادقته أو الاتصال بتطبيق Chat عضو. للمصادقة بوصفها تطبيق Chat، أضِف تطبيق Chat على المساحة
إرسال رسالة نصية نيابةً عن مستخدم
يوضح هذا القسم كيفية إرسال الرسائل نيابةً عن مستخدم باستخدام مصادقة المستخدم. من خلال مصادقة المستخدم، يمكن أن يتضمّن محتوى الرسالة نصًا فقط. ويجب أن يغفل ميزات المراسلة التي تتوفر فقط تطبيقات Chat، بما في ذلك واجهات البطاقات والتطبيقات المصغّرة التفاعلية
لطلب رقم messages.create()
باستخدام مصادقة المستخدم، يجب تحديد
الحقول التالية في الطلب:
- نطاق التفويض
يتيح إمكانية مصادقة المستخدم لهذه الطريقة. تشمل الاستخدامات التالية
النطاق
chat.messages.create
. - مرجع
Space
الذي تريد نشر الرسالة. يجب أن يكون المستخدم الذي تمت مصادقته عضوًا في مساحة. Message
مورد يمكن إنشاؤه. لتحديد محتوى الرسالة، يجب عليك تضمينtext
.
يمكنك تضمين ما يلي اختياريًا:
- الحقل
messageId
، الذي يتيح لك يمكنك تسمية الرسالة لاستخدامها في طلبات واجهة برمجة التطبيقات الأخرى. - الحقلان
thread.threadKey
وmessageReplyOption
من أجل بدء سلسلة محادثات أو الرد عليها إذا لم تكن المساحة استخدام سلاسل المحادثات، يتم تجاهل هذا الحقل.
لإرسال رسالة نصية نيابةً عن مستخدم، اتّبِع الخطوات التالية:
Python
- في دليل العمل، أنشئ ملفًا باسم
chat_create_message_user.py
أدرِج الرمز التالي في
chat_create_message_user.py
:import os.path from google.auth.transport.requests import Request from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow from googleapiclient.discovery import build from googleapiclient.errors import HttpError # Define your app's authorization scopes. # When modifying these scopes, delete the file token.json, if it exists. SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"] def main(): ''' Authenticates with Chat API via user credentials, then creates a text message in a Chat space. ''' # Start with no credentials. creds = None # Authenticate with Google Workspace # and get user authorization. flow = InstalledAppFlow.from_client_secrets_file( 'client_secrets.json', SCOPES) creds = flow.run_local_server() # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds) # Use the service endpoint to call Chat API. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstusermessage', # The text message to create. body={ 'text': '👋 🌎Hello world! Text messages can contain things like:\n\n' + '* Hyperlinks 🔗\n' + '* Emojis 😄🎉\n' + '* Mentions of other Chat users `@` \n\n' 'For details, see the <https://developers.google.com/workspace/chat/format-messages|Chat API developer documentation>.' } ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
استبدِل
SPACE
بالمعرّف من علامة التبويب الخاصة بالمساحة.name
. ويمكنك الحصول على المعرّف من خلال استدعاء طريقةspaces.list()
أو من عنوان URL الخاص بالمساحة.في دليل العمل، أنشئ النموذج وشغِّله:
python3 chat_create_message_user.py
إذا طُلب منك ذلك من خلال عنوان URL، افتح عنوان URL للسماح تطبيق Chat استنادًا إلى النطاق الذي استخدمته في طلبك.
ينشئ تطبيق Chat الرسالة وتتولى المصادقة على
نشر المستخدم الرسالة في المساحة في واجهة سطر الأوامر لديك،
تعرض واجهة برمجة التطبيقات Chat مثيل واجهة برمجة التطبيقات الجديدة
مرجع واحد (Message
)
إرسال رسالة باسم تطبيق Chat
يوضح هذا القسم كيفية إرسال الرسائل التي تحتوي على نصوص وبطاقات تطبيقات مصغّرة تفاعلية باستخدام مصادقة التطبيقات.
لطلب "messages.create()
" باستخدام مصادقة التطبيقات، يجب تحديد
الحقول التالية في الطلب:
- نطاق التفويض في
chat.bot
- مرجع
Space
الذي تريد نشر الرسالة. يجب أن يكون تطبيق Chat: عضوًا في المساحة. Message
مورد يمكن إنشاؤه. لتحديد محتوى الرسالة، يمكنك تضمين نص منسق (text
), واجهة بطاقة واحدة أو أكثر (cardsV2
), أو كليهما.
يمكنك تضمين ما يلي اختياريًا:
- الحقل
accessoryWidgets
المطلوب تضمينه الأزرار التفاعلية في أسفل الرسالة. - يتيح الحقل
privateMessageViewer
إرسال الرسالة بشكل خاص إلى مستخدم محدد. - الحقل
messageId
، الذي يتيح لك يمكنك تسمية الرسالة لاستخدامها في طلبات واجهة برمجة التطبيقات الأخرى. - الحقلان
thread.threadKey
وmessageReplyOption
من أجل بدء سلسلة محادثات أو الرد عليها إذا لم تكن المساحة استخدام سلاسل المحادثات، يتم تجاهل هذا الحقل.
الحد الأقصى لحجم الرسالة (بما في ذلك أي نصوص أو بطاقات) هو 32000 بايت. لإرسال رسالة يتجاوز حجمها هذا الحجم، يجب أن يستخدم تطبيق Chat. إرسال رسائل متعددة بدلاً من ذلك.
لإرسال رسالة تم نشرها كتطبيق Chat وتحتوي على ونص، وبطاقة، وزر قابل للنقر في أسفل الرسالة، اتّخاذ الخطوات التالية:
Python
- في دليل العمل، أنشئ ملفًا باسم
chat_create_message_app.py
أدرِج الرمز التالي في
chat_create_message_app.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Specify the Chat space where the message is posted. Obtain the ID # from the resource name, or from the space's URL. SPACE = 'spaces/SPACE' # Create a Chat message. result = chat.spaces().messages().create( # The Chat space. parent=SPACE, # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstappmessage', # The message to create with text, a card, and a button at the # bottom of the message. body= { 'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.', 'cardsV2': [{ 'cardId': 'myCardId', 'card': { 'header': { 'title': 'About this message', 'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg', 'imageType': 'CIRCLE' }, "sections": [ { "header": "Contents", "widgets": [ { "textParagraph": { "text": "🔡 <b>Text</b> which can include hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️." }}, { "textParagraph": { "text": "🖼️ A <b>card</b> to display visual elements and request information such as text 🔤, dates and times 📅, and selections ☑️." }}, { "textParagraph": { "text": "👉🔘 An <b>accessory widget</b> which adds a button to the bottom of a message." }}, ] }, { "header": "What's next", "collapsible": True, "widgets": [ { "textParagraph": { "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>." }}, { "textParagraph": { "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> the message." }}, { "textParagraph": { "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.' }} ] } ]} }], "accessoryWidgets": [ { "buttonList": { "buttons": [ { "text": "View documentation", "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.", "icon": { "material_icon": { "name": "link" } }, "onClick": { "openLink": { "url": "https://developers.google.com/workspace/chat/create-messages" } } } ] } } ] } ).execute() print(result)
استبدِل
SPACE
بالمعرّف من علامة التبويب الخاصة بالمساحة.name
. ويمكنك الحصول على المعرّف من خلال استدعاء طريقةspaces.list()
أو من عنوان URL الخاص بالمساحة.في دليل العمل، أنشئ النموذج وشغِّله:
python3 chat_create_message_app.py
ينشئ تطبيق Chat الرسالة وينشرها في
مساحة. في واجهة سطر الأوامر، تعرض واجهة برمجة التطبيقات Chat API
مثيل لمثيل ابتكارات جديدة
مرجع واحد (Message
)
إضافة تطبيقات مصغّرة تفاعلية في أسفل الرسالة
في عينة التعليمات البرمجية من القسم السابق، تعرض رسالة تطبيق Chat زرًا قابلاً للنقر في أسفل الرسالة، وتُعرف باسم أداة الملحقات. تطبيقات مصغّرة للإكسسوار تظهر بعد أي نص أو بطاقات في الرسالة. يمكنك استخدام هذه التطبيقات المصغّرة لطلب المستخدمين بالتفاعل مع رسالتك بعدة طرق، منها ما يلي:
- قيِّم دقة رسالة أو مدى رضاها.
- يمكنك الإبلاغ عن مشكلة في الرسالة أو تطبيق Chat.
- افتح رابطًا يؤدي إلى محتوى ذي صلة، مثل المستندات.
- رفض الرسائل المشابهة أو تأجيلها من تطبيق Chat لفترة زمنية محددة.
لإضافة تطبيقات مصغّرة للملحقات، يجب تضمين
accessoryWidgets[]
في نص طلبك وحدد التطبيق المصغَّر الذي تريده
لتضمينها.
تعرض الصورة التالية تطبيق Chat ملحقًا به. رسالة نصية تحتوي على التطبيقات المصغّرة للملحقات كي يتمكّن المستخدمون من تقييم تجربتهم باستخدام تطبيق Chat.
يوضح ما يلي نص الطلب الذي يؤدي إلى إنشاء رسالة نصية تحتوي على
زرين للملحقات. عندما ينقر المستخدم على زر ما، فإن
(مثل 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 API تلقائيًا . لمساعدتك في تحديد سلسلة المحادثات والرد عليها لاحقًا، يمكنك تحديد مفتاح سلسلة المحادثات في طلبك:
- في نص طلبك، حدد
thread.threadKey
. - تحديد معلَمة طلب البحث
messageReplyOption
لتحديد ما سيحدث إذا كان المفتاح موجودًا بالفعل.
لإنشاء رسالة يتم الردّ عليها على سلسلة محادثات حالية:
- يُرجى تضمين الحقل
thread
في نص طلبك. في حال ضبطها، يمكنك تحديدthreadKey
التي قمت بإنشائها. بخلاف ذلك، يجب عليك استخدامname
سلسلة المحادثات. - حدِّد معلَمة طلب البحث
messageReplyOption
.
يوضح ملف JSON التالي مثالاً لنص الطلب لرسالة نصية
تبدأ سلسلة محادثات أو يردّ عليها باستخدام المفتاح helloWorldThread
:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
تسمية رسالة
لاسترداد رسالة أو تحديدها في طلبات البيانات من واجهة برمجة التطبيقات المستقبلية، يمكنك تسمية رسالة.
من خلال إعداد الحقل messageId
في طلب messages.create()
.
تتيح لك تسمية رسالتك تحديد الرسالة بدون الحاجة إلى تخزين
الذي يعيّنه النظام من اسم مورد الرسالة (يتم تمثيله في
name
).
فعلى سبيل المثال، لاسترداد رسالة باستخدام الطريقة get()
، يمكنك استخدام طريقة
اسم المورد لتحديد الرسالة التي يجب استردادها. اسم المورد هو
بتنسيق spaces/{space}/messages/{message}
، حيث يمثل {message}
المعرّف الذي عيّنه النظام أو الاسم المخصّص الذي حدّدته عند إنشاء
.
لتسمية رسالة، حدِّد معرّفًا مخصّصًا في
messageId
عند إنشاء الرسالة. يضبط الحقل messageId
قيمة السمة
clientAssignedMessageId
في المورد Message
.
لا يمكنك تسمية رسالة إلا عند إنشائها. لا يمكنك تسمية أو تعديل مُعرّف مخصّص للرسائل الحالية. يجب أن يستوفي المعرّف المخصّص ما يلي: المتطلبات:
- يبدأ بـ
client-
. على سبيل المثال،client-custom-name
هو نطاق مخصص صالح. المعرّف، ولكنcustom-name
ليس كذلك. - يحتوي على ما يصل إلى 63 حرفًا وأحرف صغيرة وأرقام واصلات.
- أن تكون فريدة داخل مساحة لا يمكن لتطبيق Chat استخدام المعرّف المخصص نفسه لرسائل مختلفة.
تحديد المشاكل وحلّها
عند تثبيت تطبيق Google Chat أو تعرض card خطأً، تعرض واجهة Chat رسالة مفادها "حدث خطأ". أو "تعذَّرت معالجة طلبك". في بعض الأحيان، لا يمكن واجهة مستخدم Chat لا يعرض أي رسالة خطأ، ولكن يظهر تطبيق Chat أو ينتج عن بطاقة نتيجة غير متوقعة؛ على سبيل المثال، قد لا تظهر رسالة البطاقة موضع الإعلان.
على الرغم من أنه قد لا تظهر رسالة الخطأ في واجهة مستخدم Chat، تتوفر رسائل خطأ وصفية وبيانات السجل لمساعدتك في إصلاح الأخطاء عند تفعيل ميزة تسجيل الأخطاء لتطبيقات Chat للحصول على مساعدة في العرض، وتصحيح الأخطاء وإصلاح الأخطاء، فراجع تحديد مشاكل Google Chat وحلّها.
مواضيع ذات صلة
- استخدام "أداة إنشاء البطاقات" من أجل تصميم رسائل بطاقة JSON ومعاينتها لتطبيقات Chat.
- تنسيق الرسائل:
- الحصول على تفاصيل حول رسالة
- إدراج الرسائل في مساحة
- تعديل رسالة
- حذف رسالة
- تحديد المستخدمين في رسائل Google Chat
- إرسال الرسائل إلى Google Chat باستخدام الردود التلقائية الواردة على الويب