Gửi tin nhắn bằng API Google Chat

Hướng dẫn này giải thích cách gọi API của Google Chat messages.create() để thực hiện bất kỳ thao tác nào sau đây:

  • Gửi tin nhắn chứa văn bản, thẻ và tiện ích tương tác.
  • Gửi tin nhắn riêng tư cho một người dùng Chat cụ thể.
  • Bắt đầu hoặc trả lời một chuỗi tin nhắn.
  • Đặt tên cho tin nhắn để bạn có thể chỉ định trong API Chat khác yêu cầu.

Kích thước tin nhắn tối đa (bao gồm mọi văn bản hoặc thẻ) là 32.000 byte. Để gửi tin nhắn vượt quá kích thước này, ứng dụng Chat của bạn phải gửi nhiều thư.

Ngoài việc gọi phương thức messages.create(), các ứng dụng trong Chat có thể tạo và gửi thông báo để trả lời tương tác của người dùng, chẳng hạn như đăng tin nhắn chào mừng sau khi người dùng thêm ứng dụng Chat vào . Khi phản hồi nội dung tương tác, các ứng dụng trong Chat có thể sử dụng các loại tính năng nhắn tin, bao gồm cả hộp thoại tương tác và bản xem trước đường liên kết giao diện. Để trả lời người dùng, ứng dụng Chat sẽ quay lại tin nhắn một cách đồng bộ mà không cần gọi API Chat. Để tìm hiểu về cách gửi thư để phản hồi lại nội dung tương tác, hãy xem Nhận và trả lời các hoạt động tương tác với ứng dụng Google Chat.

Cách Chat hiển thị và phân bổ thuộc tính cho các tin nhắn được tạo bằng API Chat

Bạn có thể gọi phương thức messages.create() bằng xác thực ứng dụng và xác thực người dùng. Chat phân biệt người gửi tin nhắn theo cách khác tuỳ thuộc vào loại xác thực mà bạn sử dụng.

Khi bạn xác thực là ứng dụng Chat, ứng dụng Chat sẽ gửi tin nhắn.

Gọi phương thức messages.create() bằng phương thức xác thực ứng dụng.
Hình 1: Với tính năng xác thực ứng dụng, ứng dụng Chat sẽ gửi nội dung. Để lưu ý rằng người gửi không phải là người, ứng dụng Chat sẽ hiển thị App bên cạnh tên người gửi.

Khi bạn xác thực là người dùng, ứng dụng Chat sẽ gửi thay mặt cho người dùng. Chat cũng cho biết Ứng dụng nhắn tin cho tin nhắn bằng cách hiện tên ứng dụng.

Gọi phương thức messages.create() bằng phương thức xác thực người dùng.
Hình 2: Với cơ chế xác thực người dùng, người dùng gửi tin nhắn và Chat sẽ hiển thị Tên ứng dụng nhắn tin bên cạnh tên người dùng.

Hình thức xác thực cũng xác định giao diện và tính năng nhắn tin mà bạn có thể đưa vào thông báo. Với xác thực ứng dụng, Các ứng dụng nhắn tin có thể gửi tin nhắn chứa văn bản đa dạng thức, giao diện dựa trên thẻ và tiện ích tương tác. Vì người dùng Chat chỉ có thể gửi nội dung trong tin nhắn, nên bạn có thể chỉ bao gồm văn bản khi tạo thư bằng phương thức xác thực người dùng. Để tìm hiểu thêm về tính năng nhắn tin các tính năng có sẵn cho API Chat, hãy xem Tổng quan về tin nhắn trong Google Chat.

Hướng dẫn này giải thích cách sử dụng một trong hai loại xác thực để gửi thư bằng API Chat.

Điều kiện tiên quyết

Node.js

Python

Java

Apps Script

Gửi tin nhắn bằng ứng dụng Chat

Phần này giải thích cách gửi tin nhắn có chứa văn bản, thẻ và các tiện ích phụ kiện tương tác sử dụng xác thực ứng dụng.

Đã gửi thư bằng phương thức xác thực ứng dụng
Hình 4. Một ứng dụng Chat gửi tin nhắn bằng văn bản, thẻ và nút phụ kiện.

Để gọi messages.create() bằng phương thức xác thực ứng dụng, bạn phải chỉ định sau đây trong yêu cầu:

  • Phạm vi uỷ quyền chat.bot.
  • Tài nguyên Space trong đó mà bạn muốn đăng thông báo. Ứng dụng Chat phải một thành viên của không gian.
  • Message để tạo. Để xác định nội dung của thông báo, bạn có thể thêm văn bản đa dạng thức (text), một hoặc nhiều giao diện thẻ (cardsV2), hoặc cả hai.

Nếu muốn, bạn có thể thêm những thông tin sau:

Đoạn mã sau đây là ví dụ về cách ứng dụng Chat có thể gửi tin nhắn được đăng dưới dạng ứng dụng Chat có chứa văn bản, thẻ và nút có thể nhấp ở cuối thông báo:

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));
    }
  }
}

Apps Script

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);
}

Để chạy mẫu này, hãy thay thế SPACE_NAME bằng mã nhận dạng trong của không gian name. Bạn có thể lấy ID bằng cách gọi hàm Phương thức spaces.list() hoặc từ URL của không gian.

Thêm tiện ích tương tác ở cuối thư

Trong mã mẫu đầu tiên của hướng dẫn này, Thông báo của ứng dụng Chat sẽ hiển thị một nút có thể nhấp ở cuối thư, còn gọi là tiện ích phụ kiện. Tiện ích phụ kiện xuất hiện sau mọi văn bản hoặc thẻ trong tin nhắn. Bạn có thể sử dụng các tiện ích này để nhắc người dùng tương tác với thư của bạn theo nhiều cách, bao gồm:

  • Đánh giá độ chính xác hoặc mức độ hài lòng của tin nhắn.
  • Báo cáo vấn đề về tin nhắn hoặc ứng dụng Chat.
  • Mở một đường liên kết đến nội dung liên quan, chẳng hạn như tài liệu.
  • Đóng hoặc tạm ẩn các tin nhắn tương tự từ ứng dụng Chat trong một khoảng thời gian cụ thể.

Để thêm tiện ích phụ kiện, hãy thêm accessoryWidgets[] trong phần nội dung của yêu cầu và chỉ định một hoặc nhiều tiện ích bạn muốn để đưa vào.

Hình ảnh sau đây cho thấy một ứng dụng Chat bổ sung một tin nhắn văn bản có các tiện ích phụ kiện để người dùng có thể xếp hạng trải nghiệm của họ bằng ứng dụng Chat.

Tiện ích phụ kiện.
Hình 5: Tin nhắn của ứng dụng Chat có các tiện ích văn bản và phụ kiện.

Phần sau đây cho thấy nội dung của yêu cầu tạo tin nhắn văn bản bằng 2 nút phụ kiện. Khi người dùng nhấp vào một nút, hàm (chẳng hạn như doUpvote) xử lý tương tác:

{
  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"
    }}
  }]}}]
}

Gửi tin nhắn riêng tư

Các ứng dụng trong Chat có thể gửi tin nhắn ở chế độ riêng tư để tin nhắn chỉ hiển thị cho một người dùng cụ thể trong không gian. Khi một Ứng dụng Chat gửi tin nhắn riêng tư, tin nhắn hiển thị nhãn thông báo cho người dùng rằng chỉ họ mới nhìn thấy thông báo.

Để gửi tin nhắn riêng tư bằng API Chat, hãy chỉ định privateMessageViewer trong phần nội dung yêu cầu của bạn. Để chỉ định người dùng, bạn phải đặt giá trị thành tài nguyên User đại diện cho người dùng Chat. Bạn cũng có thể sử dụng Trường name của User, như trong ví dụ sau:

{
  text: "Hello private world!",
  privateMessageViewer: {
    name: "users/USER_ID"
  }
}

Để sử dụng mẫu này, hãy thay thế USER_ID có một mã nhận dạng duy nhất cho người dùng, chẳng hạn như 12345678987654321 hoặc hao@cymbalgroup.com. Để biết thêm thông tin về việc chỉ định người dùng, hãy xem Xác định và chỉ định người dùng Google Chat.

Để gửi thư một cách riêng tư, bạn phải bỏ qua các thuộc tính sau trong yêu cầu của mình:

Gửi tin nhắn văn bản thay mặt cho người dùng

Phần này giải thích cách gửi thông báo thay mặt cho người dùng bằng xác thực người dùng. Với xác thực người dùng, nội dung thư chỉ có thể chứa văn bản và phải bỏ qua các tính năng nhắn tin chỉ dành cho Các ứng dụng trong Chat, bao gồm cả giao diện thẻ và tiện ích tương tác.

Đã gửi thư có xác thực người dùng
Hình 3. Một ứng dụng Chat sẽ gửi tin nhắn văn bản vào thay mặt cho người dùng.

Để gọi messages.create() bằng phương thức xác thực người dùng, bạn phải chỉ định sau đây trong yêu cầu:

  • Phạm vi uỷ quyền có hỗ trợ xác thực người dùng cho phương pháp này. Ví dụ sau đây sử dụng phạm vi chat.messages.create.
  • Tài nguyên Space trong đó mà bạn muốn đăng thông báo. Người dùng đã xác thực phải là thành viên của .
  • Message để tạo. Để xác định nội dung thông báo, bạn phải đưa vào text .

Nếu muốn, bạn có thể thêm những thông tin sau:

Đoạn mã sau đây là ví dụ về cách ứng dụng Chat có thể gửi tin nhắn văn bản trong một không gian nhất định thay mặt cho người dùng đã xác thực:

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));
    }
  }
}

Apps Script

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);
}

Để chạy mẫu này, hãy thay thế SPACE_NAME bằng mã nhận dạng trong của không gian name . Bạn có thể lấy ID bằng cách gọi hàm Phương thức spaces.list() hoặc từ URL của không gian.

Bắt đầu hoặc trả lời trong một chuỗi tin nhắn

Đối với không gian sử dụng chuỗi, bạn có thể chỉ định liệu một thư mới sẽ bắt đầu chuỗi hay trả lời chuỗi hiện có.

Theo mặc định, tin nhắn mà bạn tạo bằng API Chat sẽ bắt đầu một phiên mới chuỗi. Để giúp bạn xác định chuỗi thư và trả lời chuỗi đó vào lúc khác, bạn có thể chỉ định một khoá luồng trong yêu cầu của bạn:

  • Trong phần nội dung yêu cầu, hãy nêu rõ thread.threadKey .
  • Chỉ định tham số truy vấn messageReplyOption để xác định điều gì sẽ xảy ra nếu khoá đã tồn tại.

Cách tạo tin nhắn trả lời chuỗi tin nhắn hiện có:

  • Trong phần nội dung của yêu cầu, hãy thêm trường thread. Nếu được đặt, bạn có thể chỉ định threadKey mà bạn đã tạo. Nếu không, bạn phải sử dụng name của chuỗi.
  • Chỉ định tham số truy vấn messageReplyOption.

Đoạn mã sau đây là ví dụ về cách ứng dụng Chat có thể gửi một tin nhắn văn bản bắt đầu hoặc trả lời một chuỗi nhất định được xác định bởi khoá của một không gian nhất định thay mặt cho người dùng đã xác thực:

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));
    }
  }
}

Apps Script

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);
}

Để chạy mẫu này, hãy thay thế nội dung sau:

  • THREAD_KEY: một khoá luồng hiện có trong không gian, hoặc để tạo một chuỗi mới, là tên duy nhất cho chuỗi.
  • SPACE_NAME: mã nhận dạng của không gian name . Bạn có thể lấy ID bằng cách gọi hàm Phương thức spaces.list() hoặc từ URL của không gian.

Đặt tên cho thông báo

Để truy xuất hoặc chỉ định một thông báo trong các lệnh gọi API sau này, bạn có thể đặt tên cho thông báo. bằng cách đặt trường messageId trong yêu cầu messages.create(). Việc đặt tên cho thông báo của bạn cho phép bạn chỉ định thông báo mà không cần lưu trữ mã nhận dạng do hệ thống chỉ định từ tên tài nguyên của thông báo (biểu thị trong name ).

Ví dụ: để truy xuất thư bằng phương thức get(), bạn sử dụng tên tài nguyên để chỉ định thông báo nào cần truy xuất. Tên tài nguyên là có định dạng là spaces/{space}/messages/{message}, trong đó {message} đại diện cho mã do hệ thống chỉ định hoặc tên tuỳ chỉnh mà bạn đặt khi tạo .

Để đặt tên cho thông báo, hãy chỉ định một mã tuỳ chỉnh trong messageId khi bạn tạo thông báo. Trường messageId đặt giá trị cho thuộc tính clientAssignedMessageId của tài nguyên Message.

Bạn chỉ có thể đặt tên cho thông báo khi tạo thông báo. Bạn không thể đặt tên hoặc sửa đổi mã tuỳ chỉnh cho tin nhắn hiện có. Mã tuỳ chỉnh phải đáp ứng các yêu cầu sau: các yêu cầu:

  • Bắt đầu bằng client-. Ví dụ: client-custom-name là một mã tuỳ chỉnh hợp lệ Mã nhận dạng, nhưng custom-name thì không.
  • Chứa tối đa 63 ký tự, chỉ chứa chữ cái viết thường, số và dấu gạch nối.
  • Là duy nhất trong một không gian. Ứng dụng Chat không thể dùng cùng một mã tuỳ chỉnh cho các thông báo khác nhau.

Đoạn mã sau đây là ví dụ về cách ứng dụng Chat có thể gửi tin nhắn văn bản kèm theo mã nhận dạng tới một không gian nhất định thay mặt cho người dùng đã xác thực:

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));
    }
  }
}

Apps Script

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);
}

Để chạy mẫu này, hãy thay thế nội dung sau:

  • SPACE_NAME: mã nhận dạng của không gian name . Bạn có thể lấy ID bằng cách gọi hàm Phương thức spaces.list() hoặc từ URL của không gian.
  • MESSAGE-ID: tên cho thông báo bắt đầu cùng với custom-. Phải riêng biệt so với bất kỳ tên thông báo nào khác do Ứng dụng Chat trong không gian được chỉ định.

Khắc phục sự cố

Khi một ứng dụng Google Chat hoặc card trả về một lỗi, thì phương thức Giao diện Chat hiển thị một thông báo với nội dung "Đã xảy ra lỗi". hoặc "Không thể xử lý yêu cầu của bạn". Đôi khi, giao diện người dùng của Chat không hiện thông báo lỗi nào ngoài ứng dụng Chat hoặc thẻ tạo ra kết quả không mong muốn; ví dụ: thông báo thẻ có thể không xuất hiện.

Mặc dù thông báo lỗi có thể không xuất hiện trong giao diện người dùng Chat, thông báo lỗi mô tả và dữ liệu nhật ký luôn có sẵn để giúp bạn sửa lỗi khi tính năng ghi nhật ký lỗi cho các ứng dụng trong Chat được bật. Để được trợ giúp xem, gỡ lỗi và sửa lỗi, hãy xem Khắc phục lỗi và khắc phục lỗi của Google Chat.