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ênMessage
. - 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
- Một tài khoản Google Workspace có quyền truy cập vào Google Chat.
- Một ứng dụng Chat đã phát hành. Để xây dựng một ứng dụng Chat, hãy làm theo phần bắt đầu nhanh sau.
- Đã đị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.
- Việc gửi tin nhắn văn bản sẽ hỗ trợ cả hai phương thức uỷ quyền sau đây:
- Xác thực người dùng với phạm vi uỷ quyền
chat.messages.create
hoặcchat.messages
. - Xác thực ứng dụng với phạm vi uỷ quyền
chat.bot
.
- Xác thực người dùng với phạm vi uỷ quyền
- Việc gửi tin nhắn thẻ cần phải xác thực ứng dụng với phạm vi uỷ quyền
chat.bot
.
- Việc gửi tin nhắn văn bản sẽ hỗ trợ cả hai phương thức uỷ quyền sau đây:
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.
- Việc gửi tin nhắn văn bản sẽ hỗ trợ cả hai phương thức uỷ quyền sau đây:
- Xác thực người dùng với phạm vi uỷ quyền
chat.messages.create
hoặcchat.messages
. - Xác thực ứng dụng với phạm vi uỷ quyền
chat.bot
.
- Xác thực người dùng với phạm vi uỷ quyền
- Để gửi tin nhắn thẻ, bạn cần xác thực ứng dụng trong phạm vi uỷ quyền
chat.bot
.
- Việc gửi tin nhắn văn bản sẽ hỗ trợ cả hai phương thức uỷ quyền sau đây:
Apps Script
- Một tài khoản Google Workspace có quyền truy cập vào Google Chat.
- Một ứng dụng Chat đã phát hành. Để xây dựng một ứng dụng Chat, hãy làm theo phần bắt đầu nhanh sau.
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:
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ềnchat.messages.create
. - Gọi phương thức
create
trên tài nguyênMessage
.
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
- 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
. Đư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)
Trong mã, hãy thay thế
SPACE
bằng tên không gian. Bạn có thể lấy từ phương thứcspaces.list()
trong API Chat hoặc từ URL của không gian.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
- 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
. Đư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()
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ứcspaces.list()
trong API Chat hoặc từ URL của không gian.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 đó:
Node.js
Python
Apps Script
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ênMessage
.
Sau đây là ví dụ về thông báo thẻ:
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
- 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
. Đư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)
Trong mã, hãy thay thế
SPACE
bằng tên không gian. Bạn có thể lấy từ phương thứcspaces.list
trong API Chat hoặc từ URL của không gian.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
- 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
. Đư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)
Trong mã, hãy thay thế
SPACE
bằng tên không gian. Bạn có thể lấy từ phương thứcspaces.list
trong API Chat hoặc từ URL của không gian.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ưngcustom-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ư
update
vàdelete
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
- 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
. Đư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)
Trong mã, hãy thay thế
SPACE
bằng tên không gian. Bạn có thể lấy từ phương thứcspaces.list
trong API Chat hoặc từ URL của không gian.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.
Chủ đề có liên quan
- Định dạng thư.
- Xem thông tin chi tiết về một tin nhắn.
- Liệt kê tin nhắn trong một không gian.
- Cập nhật thông báo.
- Xoá tin nhắn.
- Nhận dạng người dùng trong tin nhắn trên Google Chat.