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

يوضّح هذا الدليل كيفية استخدام الإجراء create() في مورد Message لواجهة برمجة التطبيقات Google Chat API لتنفيذ أيّ من الإجراءات التالية:

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

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

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

كيفية عرض Chat للرسائل التي تم إنشاؤها باستخدام Chat API وتحديد مصدرها

يمكنك استدعاء طريقة create() باستخدام مصادقة التطبيق ومصادقة المستخدم. تُحدِّد Chat مصدر الرسالة بشكل مختلف استنادًا إلى نوع المصادقة الذي تستخدمه.

عند المصادقة بصفتك تطبيق Chat، يرسل تطبيق Chat الرسالة.

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

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

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

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

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

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

Node.js

Python

Java

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

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

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

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

لاستدعاء CreateMessage() الطريقة باستخدام مصادقة التطبيق، يجب تحديد الحقول التالية في الطلب:

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

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

يعرض الرمز البرمجي التالي مثالاً على كيفية إرسال تطبيق Chat لرسالة منشورة على أنّها تطبيق Chat تحتوي على نص وبطاقة وزر يمكن النقر عليه في أسفل الرسالة:

Node.js

chat/client-libraries/cloud/create-message-app-cred.js
import {createClientWithAppCredentials} from './authentication-utils.js';

// This sample shows how to create message with app credential
async function main() {
  // Create a client
  const chatClient = createClientWithAppCredentials();

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      text: '👋🌎 Hello world! I created this message by calling ' +
            'the Chat API\'s `messages.create()` method.',
      cardsV2 : [{ card: {
        header: {
          title: 'About this message',
          imageUrl: 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
        },
        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."
              }
            }]
          }
        ]
      }}],
      accessoryWidgets: [{ buttonList: { buttons: [{
        text: 'View documentation',
        icon: { materialIcon: { name: 'link' }},
        onClick: { openLink: {
          url: 'https://developers.google.com/workspace/chat/create-messages'
        }}
      }]}}]
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_app_cred.py
from authentication_utils import create_client_with_app_credentials
from google.apps import chat_v1 as google_chat

# This sample shows how to create message with app credential
def create_message_with_app_cred():
    # Create a client
    client = create_client_with_app_credentials()

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "text": '👋🌎 Hello world! I created this message by calling ' +
                    'the Chat API\'s `messages.create()` method.',
            "cards_v2" : [{ "card": {
                "header": {
                    "title": 'About this message',
                    "image_url": 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
                },
                "sections": [{
                    "header": "Contents",
                    "widgets": [{ "text_paragraph": {
                            "text": '🔡 <b>Text</b> which can include ' +
                                    'hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.'
                        }}, { "text_paragraph": {
                            "text": '🖼️ A <b>card</b> to display visual elements' +
                                    'and request information such as text 🔤, ' +
                                    'dates and times 📅, and selections ☑️.'
                        }}, { "text_paragraph": {
                            "text": '👉🔘 An <b>accessory widget</b> which adds ' +
                                    'a button to the bottom of a message.'
                        }}
                    ]}, {
                        "header": "What's next",
                        "collapsible": True,
                        "widgets": [{ "text_paragraph": {
                                "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>."
                            }}, { "text_paragraph": {
                                "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."
                            }
                        }]
                    }
                ]
            }}],
            "accessory_widgets": [{ "button_list": { "buttons": [{
                "text": 'View documentation',
                "icon": { "material_icon": { "name": 'link' }},
                "on_click": { "open_link": {
                    "url": 'https://developers.google.com/workspace/chat/create-messages'
                }}
            }]}}]
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_app_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageAppCred.java
import com.google.apps.card.v1.Button;
import com.google.apps.card.v1.ButtonList;
import com.google.apps.card.v1.Card;
import com.google.apps.card.v1.Icon;
import com.google.apps.card.v1.MaterialIcon;
import com.google.apps.card.v1.OnClick;
import com.google.apps.card.v1.OpenLink;
import com.google.apps.card.v1.TextParagraph;
import com.google.apps.card.v1.Widget;
import com.google.apps.card.v1.Card.CardHeader;
import com.google.apps.card.v1.Card.Section;
import com.google.chat.v1.AccessoryWidget;
import com.google.chat.v1.CardWithId;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with app credential.
public class CreateMessageAppCred {

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithAppCredentials()) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 Hello world! I created this message by calling " +
                    "the Chat API\'s `messages.create()` method.")
          .addCardsV2(CardWithId.newBuilder().setCard(Card.newBuilder()
            .setHeader(CardHeader.newBuilder()
              .setTitle("About this message")
              .setImageUrl("https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg"))
            .addSections(Section.newBuilder()
              .setHeader("Contents")
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔡 <b>Text</b> which can include " +
                "hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🖼️ A <b>card</b> to display visual elements " +
                "and request information such as text 🔤, " +
                "dates and times 📅, and selections ☑️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "👉🔘 An <b>accessory widget</b> which adds " +
                "a button to the bottom of a message."))))
            .addSections(Section.newBuilder()
              .setHeader("What's next")
              .setCollapsible(true)
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔄 <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."))))))
          .addAccessoryWidgets(AccessoryWidget.newBuilder()
            .setButtonList(ButtonList.newBuilder()
              .addButtons(Button.newBuilder()
                .setText("View documentation")
                .setIcon(Icon.newBuilder()
                  .setMaterialIcon(MaterialIcon.newBuilder().setName("link")))
                .setOnClick(OnClick.newBuilder()
                  .setOpenLink(OpenLink.newBuilder()
                    .setUrl("https://developers.google.com/workspace/chat/create-messages")))))));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

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

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with app credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.bot'
 * used by service accounts.
 */
function createMessageAppCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const message = {
    text: '👋🌎 Hello world! I created this message by calling ' +
          'the Chat API\'s `messages.create()` method.',
    cardsV2 : [{ card: {
      header: {
        title: 'About this message',
        imageUrl: 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
      },
      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."
            }
          }]
        }
      ]
    }}],
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: 'View documentation',
      icon: { materialIcon: { name: 'link' }},
      onClick: { openLink: {
        url: 'https://developers.google.com/workspace/chat/create-messages'
      }}
    }]}}]
  };
  const parameters = {};

  // Make the request
  const response = Chat.Spaces.Messages.create(
    message, parent, parameters, getHeaderWithAppCredentials()
  );

  // Handle the response
  console.log(response);
}

لتنفيذ هذا المثال، استبدِل SPACE_NAME برقم التعريف من حقل name المجموعة. يمكنك الحصول على المعرّف من خلال استدعاء الطريقة ListSpaces() أو من عنوان URL للمساحة.

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

في نموذج الرموز البرمجية الأول من هذا الدليل، تعرِض رسالة تطبيق 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 وتحديدهم.

لإرسال رسالة خاصة، يجب حذف ما يلي في طلبك:

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

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

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

لاستدعاء طريقة CreateMessage() باستخدام مصادقة المستخدم، يجب تحديد الحقول التالية في الطلب:

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

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

يعرض الرمز البرمجي التالي مثالاً على كيفية إرسال تطبيق Chat لرسالة نصية في مساحة معيّنة نيابةً عن مستخدم تم مصادقة هويته:

Node.js

chat/client-libraries/cloud/create-message-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      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>.'
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

def create_message_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "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>.'
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with user credential.
public class CreateMessageUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 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>."));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

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

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const message = {
    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>.'
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent);

  // Handle the response
  console.log(response);
}

لتنفيذ هذا المثال، استبدِل SPACE_NAME برقم التعريف من حقل name المجموعة. يمكنك الحصول على المعرّف من خلال استدعاء الوسيطة ListSpaces() أو من عنوان URL للمساحة.

بدء سلسلة محادثات أو الرد عليها

بالنسبة إلى المساحات التي تستخدم سلاسل المحادثات، يمكنك تحديد ما إذا كانت رسالة جديدة تبدأ سلسلة محادثات أو ردودًا على سلسلة محادثات حالية.

تبدأ الرسائل التي تنشئها باستخدام Chat API تلقائيًا في سلسلسة محادثات جديدة. لمساعدتك في تحديد سلسلة المحادثات والردّ عليها لاحقًا، يمكنك تحديد مفتاح سلسلة المحادثات في طلبك:

  • في نص الطلب، حدِّد الحقل thread.threadKey.
  • حدِّد مَعلمة الطلب messageReplyOption لتحديد ما يحدث إذا كان المفتاح متوفّرًا.

لإنشاء رسالة تردّ على سلسلة محادثات حالية:

  • أدرِج حقل thread في نص طلبك. في حال ضبطها، يمكنك تحديد threadKey الذي أنشأته. بخلاف ذلك، عليك استخدام رمز name المخصص للمحادثة.
  • حدِّد مَعلمة طلب البحث messageReplyOption.

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

Node.js

chat/client-libraries/cloud/create-message-user-cred-thread-key.js
import {createClientWithUserCredentials} from './authentication-utils.js';
const {MessageReplyOption} = require('@google-apps/chat').protos.google.chat.v1.CreateMessageRequest;

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential with thread key
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Creates the message as a reply to the thread specified by thread_key
    // If it fails, the message starts a new thread instead
    messageReplyOption: MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
    message: {
      text: 'Hello with user credential!',
      thread: {
        // Thread key specifies a thread and is unique to the chat app
        // that sets it
        threadKey: 'THREAD_KEY'
      }
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred_thread_key.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

import google.apps.chat_v1.CreateMessageRequest.MessageReplyOption

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with thread key
def create_message_with_user_cred_thread_key():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Creates the message as a reply to the thread specified by thread_key.
        # If it fails, the message starts a new thread instead.
        message_reply_option = MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
        message = {
            "text": "Hello with user credential!",
            "thread": {
                # Thread key specifies a thread and is unique to the chat app
                # that sets it.
                "thread_key": "THREAD_KEY"
            }
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_thread_key()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredThreadKey.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.CreateMessageRequest.MessageReplyOption;
import com.google.chat.v1.Message;
import com.google.chat.v1.Thread;

// This sample shows how to create message with a thread key with user
// credential.
public class CreateMessageUserCredThreadKey {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        // Creates the message as a reply to the thread specified by thread_key.
        // If it fails, the message starts a new thread instead.
        .setMessageReplyOption(
          MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD)
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!")
          // Thread key specifies a thread and is unique to the chat app
          // that sets it.
          .setThread(Thread.newBuilder().setThreadKey("THREAD_KEY")));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

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

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with thread key
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredThreadKey() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  // Creates the message as a reply to the thread specified by thread_key
  // If it fails, the message starts a new thread instead
  const messageReplyOption = 'REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD';
  const message = {
    text: 'Hello with user credential!',
    thread: {
      // Thread key specifies a thread and is unique to the chat app
      // that sets it
      threadKey: 'THREAD_KEY'
    }
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageReplyOption: messageReplyOption
  });

  // Handle the response
  console.log(response);
}

لتشغيل هذا النموذج، استبدل ما يلي:

  • THREAD_KEY: مفتاح سلسلة محادثات حالية في المساحة، أو لإنشاء سلسلة محادثات جديدة، اسم فريد لسلسلة المحادثات
  • ‫SPACE_NAME: المعرّف من حقل name الخاص بالمساحة يمكنك الحصول على المعرّف من خلال استدعاء الطريقة ListSpaces() أو من عنوان URL للمساحة.

تسمية رسالة

لاسترداد رسالة أو تحديدها في طلبات البيانات من واجهة برمجة التطبيقات المستقبلية، يمكنك تسمية رسالة من خلال ضبط الحقل messageId في طلبك. يتيح لك تسمية رسالتك تحديد الرسالة بدون الحاجة إلى تخزين الرقم التعريفي الذي يحدّده النظام من اسم المورد للرسالة (الممثّل في الحقل name ).

على سبيل المثال، لاسترداد رسالة باستخدام الطريقة get()، يمكنك استخدام اسم المورد لتحديد الرسالة المطلوب استردادها. يتم تنسيق اسم المورد على النحو التالي: spaces/{space}/messages/{message}، حيث يمثّل {message} رقم التعريف الذي عيّنه النظام أو الاسم المخصّص الذي ضبطته عند إنشاء الرسالة.

لتسمية رسالة، حدِّد رقم تعريف مخصّصًا في الحقل messageId عند إنشاء الرسالة. يضبط الحقل messageId قيمة حقل clientAssignedMessageId الموارد Message.

لا يمكنك تسمية رسالة إلا عند إنشائها. لا يمكنك تسمية رقم تعريف مخصّص للرسائل الحالية أو تعديله. يجب أن يستوفي المعرّف المخصّص ال requirements التالية:

  • يبدأ بـ client-. على سبيل المثال، client-custom-name هو معرّف مخصّص مقبولاً، ولكن custom-name ليس كذلك.
  • يحتوي على ما يصل إلى 63 حرفًا وأحرفًا لاتينية صغيرة وأرقامًا و واصلات فقط.
  • أن تكون فريدة من نوعها ضمن مساحة لا يمكن لتطبيق Chat استخدام المعرّف المخصّص نفسه لرسائل مختلفة.

يعرض الرمز التالي مثالاً على كيفية إرسال تطبيق Chat رسالة نصية تتضمّن معرّفًا إلى مساحة معيّنة نيابةً عن مستخدم تم مصادقة هويته:

Node.js

chat/client-libraries/cloud/create-message-user-cred-message-id.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create message with user credential with message id
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Message id lets chat apps get, update or delete a message without needing
    // to store the system assigned ID in the message's resource name
    messageId: 'client-MESSAGE-ID',
    message: { text: 'Hello with user credential!' }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

chat/client-libraries/cloud/create_message_user_cred_message_id.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with message id
def create_message_with_user_cred_message_id():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Message id let chat apps get, update or delete a message without needing
        # to store the system assigned ID in the message's resource name.
        message_id = "client-MESSAGE-ID",
        message = {
            "text": "Hello with user credential!"
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_message_id()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredMessageId.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with message id specified with user
// credential.
public class CreateMessageUserCredMessageId {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!"))
        // Message ID lets chat apps get, update or delete a message without
        // needing to store the system assigned ID in the message's resource
        // name.
        .setMessageId("client-MESSAGE-ID");
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

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

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with message id
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredMessageId() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  // Message id lets chat apps get, update or delete a message without needing
  // to store the system assigned ID in the message's resource name
  const messageId = 'client-MESSAGE-ID';
  const message = { text: 'Hello with user credential!' };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageId: messageId
  });

  // Handle the response
  console.log(response);
}

لتشغيل هذا العيّنة، استبدِل ما يلي:

  • SPACE_NAME: رقم التعريف من الحقل name الخاص بالمساحة. يمكنك الحصول على المعرّف من خلال استدعاء الوسيطة ListSpaces() أو من عنوان URL للمساحة.
  • MESSAGE-ID: اسم للرسالة التي تبدأ بـ custom-. ويجب أن يكون فريدًا عن أي أسماء رسائل أخرى ينشئها تطبيق Chat في المساحة المحدّدة.

تحديد المشاكل وحلّها

عندما يعرض تطبيق Google Chat أو البطاقة خطأ، تظهر في واجهة Chat رسالة تفيد بأنّ "حدث خطأ". أو "تعذّرت معالجة طلبك". في بعض الأحيان، لا يعرض واجهة مستخدم Chat أي رسالة خطأ، ولكن ينتج عن تطبيق Chat أو البطاقة نتيجة غير متوقّعة. على سبيل المثال، قد لا تظهر رسالة البطاقة .

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