Gửi tin nhắn

Hướng dẫn này giải thích các cách mà ứng dụng Google Chat có thể gửi tin nhắn:

  • Gửi tin nhắn văn bản và tin nhắn thẻ theo thời gian thực bằng cách phản hồi tương tác của người dùng.
  • Gửi không đồng bộ tin nhắn văn bản và thẻ bằng cách gọi phương thức create trên tài nguyên Message.
  • Bắt đầu hoặc trả lời một chuỗi tin nhắn.
  • Gửi và đặt tên cho tin nhắn.

Tài nguyên Message đại diện cho tin nhắn văn bản hoặc thẻ trong Google Chat. Bạn có thể create, get, update hoặc delete tin nhắn trong API Google Chat bằng cách gọi các phương thức tương ứng. Để tìm hiểu thêm về tin nhắn văn bản và tin nhắn thẻ, hãy xem bài viết Tổng quan về tin nhắn trong Google Chat.

Thay vì gọi phương thức create trên tài nguyên Message của API Google Chat để gửi không đồng bộ tin nhắn văn bản hoặc tin nhắn thẻ, các ứng dụng Google Chat cũng có thể tạo tin nhắn để phản hồi hoạt động tương tác của người dùng theo thời gian thực. Phản hồi cho hoạt động tương tác của người dùng không yêu cầu xác thực và hỗ trợ các loại tin nhắn khác, bao gồm cả hộp thoại tương tác và bản xem trước đường liên kết. Để biết thông tin chi tiết, hãy xem phần Nhận và trả lời hoạt động tương tác bằng ứng dụng Google Chat.

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

Node.js

Python

  • Python 3.6 trở lên
  • Công cụ quản lý gói pip
  • Các thư viện ứng dụng mới nhất của Google dành cho Python. Để cài đặt hoặc cập nhật các ứng dụng đó, hãy chạy lệnh sau trong giao diện dòng lệnh của bạn:

    pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
    
  • Một ứng dụng Chat đã phát hành. Để tạo và phát hành một ứng dụng Chat, hãy xem phần Tạo ứng dụng Google Chat.

  • Đã định cấu hình uỷ quyền để ứng dụng Chat gửi tin nhắn không đồng bộ. Không cần cấu hình uỷ quyền để gửi thông báo theo thời gian thực.

Apps Script

Gửi tin nhắn văn bản

Phần này mô tả cách gửi tin nhắn văn bản theo hai cách sau:

  • Gửi tin nhắn văn bản theo thời gian thực bằng cách phản hồi tương tác của người dùng.
  • Gửi tin nhắn văn bản bằng cách gọi API Google Chat một cách không đồng bộ.

Gửi tin nhắn văn bản theo thời gian thực

Trong ví dụ này, ứng dụng Chat của bạn sẽ tạo và gửi tin nhắn văn bản bất cứ khi nào ứng dụng được thêm vào một không gian. Để tìm hiểu các phương pháp hay nhất dành cho người dùng mới tham gia, hãy xem bài viết Giúp người dùng và không gian làm quen với quá trình làm quen hữu ích.

Để gửi tin nhắn văn bản khi người dùng thêm ứng dụng Chat vào một không gian, ứng dụng Chat sẽ phản hồi một sự kiện tương tác ADDED_TO_SPACE. Để phản hồi các sự kiện tương tác ADDED_TO_SPACE bằng tin nhắn văn bản, hãy sử dụng mã sau:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if(req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

Mã mẫu trả về tin nhắn văn bản sau:

Ví dụ về thông báo giới thiệu.

Gửi tin nhắn văn bản không đồng bộ

Phần sau đây giải thích cách gửi tin nhắn văn bản không đồng bộ với phương thức xác thực ứng dụng và xác thực người dùng.

Để gửi tin nhắn văn bản, hãy chuyển thông tin sau trong yêu cầu của bạn:

  • Với phương thức xác thực ứng dụng, hãy chỉ định phạm vi uỷ quyền chat.bot. Với phương thức xác thực người dùng, hãy chỉ định phạm vi uỷ quyền chat.messages.create.
  • Gọi phương thức create trên tài nguyên Message.

Gửi tin nhắn văn bản bằng phương thức xác thực ứng dụng

Dưới đây là cách gửi tin nhắn văn bản bằng tính năng xác thực ứng dụng:

Python

  1. Trong thư mục đang làm việc, hãy tạo một tệp có tên chat_create_text_message_app.py.
  2. Đưa mã sau vào chat_create_text_message_app.py:

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'credentials.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # Create a Chat message.
    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',
    
        # The message to create.
        body={'text': 'Hello, world!'}
    
    ).execute()
    
    print(result)
    
  3. Trong mã, hãy thay thế SPACE bằng tên không gian. Bạn có thể lấy từ phương thức spaces.list() trong API Chat hoặc từ URL của không gian.

  4. Trong thư mục đang làm việc, hãy tạo và chạy mẫu:

    python3 chat_create_text_message_app.py
    

API Chat trả về một bản sao của Message có thông tin chi tiết về tin nhắn được gửi.

Gửi tin nhắn văn bản bằng phương thức xác thực người dùng

Dưới đây là cách gửi tin nhắn văn bản bằng quy trình xác thực người dùng:

Python

  1. Trong thư mục đang làm việc, hãy tạo một tệp có tên chat_create_text_message_user.py.
  2. Đưa mã sau vào chat_create_text_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',
    
            # The message to create.
            body={'text': 'Hello, world!'}
    
        ).execute()
    
        # Prints details about the created membership.
        print(result)
    
    if __name__ == '__main__':
        main()
    
  3. Trong mã, hãy thay thế SPACE bằng tên không gian. Bạn có thể lấy tên này từ phương thức spaces.list() trong API Chat hoặc từ URL của không gian.

  4. Trong thư mục đang làm việc, hãy tạo và chạy mẫu:

    python3 chat_create_text_message_user.py
    

API Chat trả về một bản sao của Message có thông tin chi tiết về tin nhắn được gửi.

Gửi tin nhắn bằng thẻ

Phần này mô tả cách gửi thông báo thẻ theo 2 cách sau:

  • Gửi tin nhắn thẻ theo thời gian thực bằng cách phản hồi tương tác của người dùng.
  • Gửi tin nhắn thẻ bằng cách gọi API Google Chat một cách không đồng bộ.

Gửi tin nhắn thẻ theo thời gian thực

Các ứng dụng nhắn tin có thể tạo tin nhắn thẻ để phản hồi một hoạt động tương tác của người dùng, chẳng hạn như khi người dùng gửi tin nhắn cho ứng dụng Chat hoặc thêm ứng dụng Chat vào một không gian. Để tìm hiểu thêm về cách phản hồi hoạt động tương tác của người dùng, hãy xem phần Nhận và phản hồi các sự kiện tương tác trong ứng dụng Chat.

Trong ví dụ này, người dùng gửi tin nhắn đến ứng dụng Chat và ứng dụng Chat đó sẽ phản hồi bằng cách gửi một tin nhắn thẻ cho biết tên và hình đại diện của người dùng đó:

Ứng dụng Chat phản hồi bằng một thẻ có tên hiển thị và hình đại diện của người gửi.

Node.js

nút/hình đại diện/ứng dụng lập chỉ mục.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-app/main.py
from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

Apps Script

apps-script/avatar-app/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Gửi tin nhắn thẻ không đồng bộ

Để gửi tin nhắn thẻ, hãy chuyển thông tin sau trong yêu cầu của bạn:

  • Với phương thức xác thực ứng dụng, hãy chỉ định phạm vi uỷ quyền chat.bot. Bạn không thể gửi tin nhắn thẻ với xác thực người dùng.
  • Gọi phương thức create trên tài nguyên Message.

Sau đây là ví dụ về thông báo thẻ:

Một thông báo thẻ được gửi bằng API Chat.

Dưới đây là cách gửi tin nhắn thẻ bằng phương thức xác thực ứng dụng:

Python

  1. Trong thư mục đang làm việc, hãy tạo một tệp có tên chat_create_card_message.py.
  2. Đưa mã sau vào chat_create_card_message.py:

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'credentials.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # Create a Chat message.
    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',
    
        # The message to create.
        body=
        {
          'cardsV2': [{
            'cardId': 'createCardMessage',
            'card': {
              'header': {
                'title': 'A card message!',
                'subtitle': 'Created with the Chat API',
                'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
                'imageType': 'CIRCLE'
              },
              'sections': [
                {
                  'widgets': [
                    {
                      'buttonList': {
                        'buttons': [
                          {
                            'text': 'Read the docs!',
                            'onClick': {
                              'openLink': {
                                'url': 'https://developers.google.com/chat'
                              }
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              ]
            }
          }]
        }
    
    ).execute()
    
    print(result)
    
  3. Trong mã, hãy thay thế SPACE bằng tên không gian. Bạn có thể lấy từ phương thức spaces.list trong API Chat hoặc từ URL của không gian.

  4. Trong thư mục đang làm việc, hãy tạo và chạy mẫu:

    python3 chat_create_card_message.py
    

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

Để bắt đầu một chuỗi tin nhắn, hãy gửi một tin nhắn và để trống thread.name; Google Chat sẽ điền nội dung này khi tạo chuỗi. Nếu muốn, để tuỳ chỉnh tên của luồng, hãy chỉ định trường thread.threadKey.

Để trả lời một chuỗi tin nhắn, hãy gửi một tin nhắn chỉ định trường threadKey hoặc name của chuỗi tin nhắn đó. Nếu chuỗi tin nhắn do một người hoặc một ứng dụng Chat khác tạo, bạn phải sử dụng trường thread.name.

Nếu không tìm thấy luồng phù hợp, bạn có thể chỉ định xem một thông báo sẽ bắt đầu một luồng mới hay không được đăng bằng cách đặt trường messageReplyOption.

Sau đây là cách bắt đầu hoặc trả lời một chuỗi có trường threadKey được xác định là nameOfThread:

Python

  1. Trong thư mục đang làm việc, hãy tạo một tệp có tên chat_create_message_thread.py.
  2. Đưa mã sau vào chat_create_message_thread.py:

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'credentials.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # Create a Chat message.
    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',
    
        # Whether to start a thread or reply to an existing one.
        #
        # Required when threading is enabled in a space unless starting a
        # thread.  Ignored in other space types. Threading is enabled when
        # space.spaceThreadingState is THREADED_MESSAGES.
        #
        # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread
        # if one exists, otherwise it starts a new one.
        messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD',
    
        # The message body.
        body={
    
            # The message to create.
            'text': 'Start or reply to another message in a thread!',
    
            # The thread to start or reply to.
            'thread': {
                'threadKey': 'nameOfThread'
            }
        }
    
    ).execute()
    
    print(result)
    
  3. Trong mã, hãy thay thế SPACE bằng tên không gian. Bạn có thể lấy từ phương thức spaces.list trong API Chat hoặc từ URL của không gian.

  4. Trong thư mục đang làm việc, hãy tạo và chạy mẫu:

    python3 chat_create_message_thread.py
    

API Chat trả về một bản sao của Message có thông tin chi tiết về tin nhắn được gửi.

Gửi và đặt tên cho tin nhắn

Phần này giải thích cách gửi thư với tên tuỳ chỉnh. Bạn sử dụng tên thông báo để nhận, cập nhật hoặc xoá thông báo. Việc chỉ định tên tuỳ chỉnh cũng cho phép ứng dụng Chat gọi lại tin nhắn mà không cần lưu thông báo name khỏi nội dung phản hồi được trả về khi gửi tin nhắn.

Việc chỉ định tên tuỳ chỉnh không thay thế trường name đã tạo (tên tài nguyên của thông báo). Thay vào đó, thuộc tính này sẽ đặt tên tuỳ chỉnh là trường clientAssignedMessageId mà bạn có thể tham chiếu khi xử lý các thao tác sau này, chẳng hạn như cập nhật hoặc xoá thông báo.

Tên tuỳ chỉnh phải đáp ứng các yêu cầu sau:

  • Bắt đầu bằng client-. Ví dụ: client-custom-name là tên tuỳ chỉnh hợp lệ, nhưng custom-name thì không.
  • Chỉ chứa chữ cái viết thường, số và dấu gạch nối.
  • Không được dài quá 63 ký tự.
  • Việc chỉ định tên tuỳ chỉnh đã dùng trong khi gửi thông báo sẽ trả về lỗi, nhưng các phương thức khác như updatedelete sẽ hoạt động như dự kiến.

Dưới đây là cách gửi và đặt tên cho thông báo:

Python

  1. Trong thư mục đang làm việc, hãy tạo một tệp có tên chat_create_named_message.py.
  2. Đưa mã sau vào chat_create_named_message.py:

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'credentials.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # Create a Chat message with a custom name.
    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',
    
        # Custom name for the message used to facilitate later operations.
        messageId='client-custom-name',
    
        # The message to create.
        body={'text': 'Hello, world!'}
    
    ).execute()
    
    print(result)
    
  3. Trong mã, hãy thay thế SPACE bằng tên không gian. Bạn có thể lấy từ phương thức spaces.list trong API Chat hoặc từ URL của không gian.

  4. Trong thư mục đang làm việc, hãy tạo và chạy mẫu:

    python3 chat_create_named_message.py
    

API Chat trả về một bản sao của Message có thông tin chi tiết về tin nhắn được gửi.

Khắc phục sự cố

Khi ứng dụng Google Chat hoặc thẻ trả về lỗi, giao diện Chat sẽ hiển thị thông báo "Đã 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 nhưng ứng dụng hoặc thẻ trong Chat tạo ra kết quả không mong muốn (ví dụ: thông báo bằng thẻ có thể không xuất hiện).

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