إرسال رسالة باستخدام Google Chat API

يشرح هذا الدليل طريقة استدعاء واجهة برمجة تطبيقات 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 الرسالة.

استدعاء طريقة message.create() مع مصادقة التطبيق.
الشكل 1: من خلال مصادقة التطبيق، يرسل تطبيق Chat الرسالة. للإشارة إلى أنّ المُرسِل ليس شخصًا، يعرض تطبيق Chat الاسم App بجانب اسمه.

عند المصادقة كمستخدم، يرسل تطبيق Chat نيابةً عن المستخدم. ينسب Chat أيضًا تطبيق Chat على الرسالة من خلال عرض الاسم

استدعاء طريقة message.create() بمصادقة المستخدم.
الشكل 2: من خلال مصادقة المستخدم، يُرسِل المستخدم الرسالة، ويعرض Chat اسم تطبيق Chat بجانب اسم المستخدم

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

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

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

Python

  • Python 3.6 أو أعلى
  • أداة إدارة حزم pip
  • أحدث مكتبات عملاء Google. لتثبيت التطبيقات أو تحديثها، قم بتشغيل الأمر التالي في واجهة سطر الأوامر: 
    pip3 install --upgrade google-api-python-client google-auth-oauthlib

إرسال رسالة نصية نيابةً عن مستخدم

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

تم إرسال الرسالة مع مصادقة المستخدم.
الشكل 3. يُرسِل تطبيق Chat رسالة نصية على نيابةً عن المستخدم.

لطلب رقم messages.create() باستخدام مصادقة المستخدم، يجب تحديد الحقول التالية في الطلب:

  • نطاق التفويض يتيح إمكانية مصادقة المستخدم لهذه الطريقة. تشمل الاستخدامات التالية النطاق chat.messages.create.
  • مرجع Space الذي تريد نشر الرسالة. يجب أن يكون المستخدم الذي تمت مصادقته عضوًا في مساحة.
  • Message مورد يمكن إنشاؤه. لتحديد محتوى الرسالة، يجب عليك تضمين text .

يمكنك تضمين ما يلي اختياريًا:

  • الحقل messageId، الذي يتيح لك يمكنك تسمية الرسالة لاستخدامها في طلبات واجهة برمجة التطبيقات الأخرى.
  • الحقلان thread.threadKey وmessageReplyOption من أجل بدء سلسلة محادثات أو الرد عليها إذا لم تكن المساحة استخدام سلاسل المحادثات، يتم تجاهل هذا الحقل.

لإرسال رسالة نصية نيابةً عن مستخدم، اتّبِع الخطوات التالية:

Python

  1. في دليل العمل، أنشئ ملفًا باسم chat_create_message_user.py

  2. أدرِج الرمز التالي في 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 الخاص بالمساحة.

  3. في دليل العمل، أنشئ النموذج وشغِّله:

    python3 chat_create_message_user.py

  4. إذا طُلب منك ذلك من خلال عنوان URL، افتح عنوان URL للسماح تطبيق Chat استنادًا إلى النطاق الذي استخدمته في طلبك.

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

إرسال رسالة باسم تطبيق Chat

يوضح هذا القسم كيفية إرسال الرسائل التي تحتوي على نصوص وبطاقات تطبيقات مصغّرة تفاعلية باستخدام مصادقة التطبيقات.

تم إرسال الرسالة باستخدام مصادقة التطبيق.
الشكل 4. يُرسِل تطبيق في Chat رسالة باستخدام ونص وبطاقة وزر للملحقات.

لطلب "messages.create()" باستخدام مصادقة التطبيقات، يجب تحديد الحقول التالية في الطلب:

  • نطاق التفويض في chat.bot
  • مرجع Space الذي تريد نشر الرسالة. يجب أن يكون تطبيق Chat: عضوًا في المساحة.
  • Message مورد يمكن إنشاؤه. لتحديد محتوى الرسالة، يمكنك تضمين نص منسق (text), واجهة بطاقة واحدة أو أكثر (cardsV2), أو كليهما.

يمكنك تضمين ما يلي اختياريًا:

الحد الأقصى لحجم الرسالة (بما في ذلك أي نصوص أو بطاقات) هو 32000 بايت. لإرسال رسالة يتجاوز حجمها هذا الحجم، يجب أن يستخدم تطبيق Chat. إرسال رسائل متعددة بدلاً من ذلك.

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

Python

  1. في دليل العمل، أنشئ ملفًا باسم chat_create_message_app.py

  2. أدرِج الرمز التالي في 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 الخاص بالمساحة.

  3. في دليل العمل، أنشئ النموذج وشغِّله:

    python3 chat_create_message_app.py

ينشئ تطبيق Chat الرسالة وينشرها في مساحة. في واجهة سطر الأوامر، تعرض واجهة برمجة التطبيقات Chat API مثيل لمثيل ابتكارات جديدة مرجع واحد (Message)

إضافة تطبيقات مصغّرة تفاعلية في أسفل الرسالة

في عينة التعليمات البرمجية من القسم السابق، تعرض رسالة تطبيق Chat زرًا قابلاً للنقر في أسفل الرسالة، وتُعرف باسم أداة الملحقات. تطبيقات مصغّرة للإكسسوار تظهر بعد أي نص أو بطاقات في الرسالة. يمكنك استخدام هذه التطبيقات المصغّرة لطلب المستخدمين بالتفاعل مع رسالتك بعدة طرق، منها ما يلي:

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

لإضافة تطبيقات مصغّرة للملحقات، يجب تضمين accessoryWidgets[] في نص طلبك وحدد التطبيق المصغَّر الذي تريده لتضمينها.

تعرض الصورة التالية تطبيق Chat ملحقًا به. رسالة نصية تحتوي على التطبيقات المصغّرة للملحقات كي يتمكّن المستخدمون من تقييم تجربتهم باستخدام تطبيق Chat.

التطبيق المصغّر للملحق
الشكل 5: رسالة تطبيق 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 وحلّها.