Hướng dẫn này giải thích các cách mà các ứng dụng Google Chat có thể gửi thư:
- 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 người dùng tương tác.
- Gửi tin nhắn văn bản và tin nhắn thẻ một cách không đồng bộ 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.
Chiến lược phát hành đĩa đơn
Tài nguyên Message
biểu thị một
văn bản
hoặc
thẻ
tin nhắn trong Google Chat. Bạn có thể
create
, get
, update
hoặc delete
một 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
Tổng quan về tin nhắn trong Google Chat.
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. Nếu một tin nhắn vượt quá kích thước này, ứng dụng Chat của bạn có thể gửi nhiều thư.
Thay vì gọi phương thức create
trên tài nguyên Message
của
API của Google Chat để gửi tin nhắn văn bản hoặc tin nhắn thẻ một cách không đồng bộ,
Các ứng dụng Google Chat cũng có thể tạo tin nhắn để phản hồi tương tác của người dùng trong
theo thời gian thực. Phản hồi cho 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 thông báo khác, bao gồm cả hộp thoại và đường liên kết tương tác
bản xem trước. Để biết thông tin chi tiết, 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.
Điều kiện tiên quyết
Node.js
- Ứng dụng Google Chat. Cách tạo một ứng dụng Chat bằng dịch vụ HTTP, hãy hoàn tất bắt đầu nhanh.
- Đã thiết lập chế độ uỷ quyền để ứng dụng Chat gửi
thư không đồng bộ. Bạn không cần thiết lập cấu hình uỷ quyền để gửi
tin nhắn theo thời gian thực.
- Đang gửi một
tin nhắn văn bản
hỗ trợ cả hai phương thức uỷ quyền sau:
- Xác thực người dùng
với sự uỷ quyền
chat.messages.create
hoặcchat.messages
phạm vi. - 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 sự uỷ quyền
- Đang gửi một
thông báo thẻ
cần
xác thực ứng dụng
với phạm vi uỷ quyền
chat.bot
.
- Đang gửi một
tin nhắn văn bản
hỗ trợ cả hai phương thức uỷ quyền sau:
Python
- Ứng dụng Google Chat. Cách tạo một ứng dụng Chat bằng dịch vụ HTTP, hãy hoàn tất bắt đầu nhanh.
- Đã thiết lập chế độ uỷ quyền để ứng dụng Chat gửi
thư không đồng bộ. Bạn không cần thiết lập cấu hình uỷ quyền để gửi
tin nhắn theo thời gian thực.
- Đang gửi một
tin nhắn văn bản
hỗ trợ cả hai phương thức uỷ quyền sau:
- Xác thực người dùng
với sự uỷ quyền
chat.messages.create
hoặcchat.messages
phạm vi. - 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 sự uỷ quyền
- Đang gửi một
thông báo thẻ
cần
xác thực ứng dụng
với phạm vi uỷ quyền
chat.bot
.
- Đang gửi một
tin nhắn văn bản
hỗ trợ cả hai phương thức uỷ quyền sau:
Apps Script
- Ứng dụng Google Chat. Cách tạo một ứng dụng Chat trong Apps Script, hãy hoàn tất bắt đầu nhanh.
- Đã thiết lập chế độ uỷ quyền để ứng dụng Chat gửi
thư không đồng bộ. Bạn không cần thiết lập cấu hình uỷ quyền để gửi
tin nhắn theo thời gian thực.
- Đang gửi một
tin nhắn văn bản
hỗ trợ cả hai phương thức uỷ quyền sau:
- Xác thực người dùng
với sự uỷ quyền
chat.messages.create
hoặcchat.messages
phạm vi. - 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 sự uỷ quyền
- Đang gửi một
thông báo thẻ
cần
xác thực ứng dụng
với phạm vi uỷ quyền
chat.bot
.
- Đang gửi một
tin nhắn văn bản
hỗ trợ cả hai phương thức uỷ quyền 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 một 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 theo 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 sẽ tạo và gửi tin nhắn văn bản tin nhắn mỗi khi cuộc trò chuyện đó được thêm vào không gian. Để tìm hiểu về các phương pháp hay nhất cho người dùng làm quen với ứng dụng, xem Giúp mọi người và không gian bắt đầu bằng cách giới thiệu hữu ích.
Để gửi tin nhắn văn bản khi người dùng thêm ứng dụng Chat của bạn
với một không gian, ứng dụng Chat của bạn
phản hồi một ADDED_TO_SPACE
sự kiện tương tác. Để phản hồi
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 sẽ 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ộ bằng 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 những thông tin sau vào yêu cầu:
- 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ằng 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ênMessage
tài nguyên.
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 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 apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # 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ã, thay thế
SPACE
bằng tên không gian, mà bạn có thể lấy từ Phương thứcspaces.list()
trong API Chat hoặc qua URL của một 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 phiên bản của
Message
nêu chi tiết tin nhắn được gửi.
Gửi tin nhắn văn bản 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 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 message. print(result) if __name__ == '__main__': main()
Trong mã, thay thế
SPACE
bằng tên không gian, mà bạn có thể lấy từ phương thứcspaces.list()
trong API Chat hoặc qua URL của một 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 phiên bản của
Message
nêu chi tiết tin nhắn được gửi.
Gửi tin nhắn qua thẻ
Phần này mô tả cách gửi thông báo thẻ theo hai cách sau:
- Gửi thông báo 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 theo cách không đồng bộ.
Gửi tin nhắn thẻ theo thời gian thực
Các ứng dụng trong Chat có thể tạo tin nhắn qua thẻ để trả lời người dùng tương tác, chẳng hạn như khi người dùng gửi ứng dụng Chat nhắn tin 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 tương tác của người dùng, hãy xem Nhận và trả lời Tương tác với ứng dụng Chat sự kiện.
Trong ví dụ này, một 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 tin nhắn thẻ hiển thị tên và hình đại diện của người dùng:
Node.js
Python
Apps Script
Ví dụ này gửi thông báo thẻ bằng cách quay lại tệp JSON của thẻ. Bạn cũng có thể sử dụng Dịch vụ thẻ Apps Script.
Gửi thông báo thẻ theo cách không đồng bộ
Để gửi một thông báo thẻ, chuyển nội dung sau vào 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 thông báo thẻ có xác thực người dùng. - Gọi
Phương thức
create
trênMessage
tài nguyên.
Sau đây là ví dụ về thông báo dạng thẻ:
Dưới đây là cách gửi thông báo 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 apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # 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ã, thay thế
SPACE
bằng tên không gian, mà bạn có thể lấy từ Phương thứcspaces.list
trong API Chat hoặc qua URL của một 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 tin nhắn và rời đi
thread.name
trống; Google Chat sẽ điền sẵn chuỗi này khi bạn tạo chuỗi trò chuyện. (Không bắt buộc)
tuỳ chỉnh tên chuỗi, chỉ định
thread.threadKey
.
Để trả lời một chuỗi thư, hãy gửi một tin nhắn nêu rõ thời gian
Trường threadKey
hoặc name
. Nếu chuỗi tin nhắn là do một người hoặc người khác tạo
là ứng dụng nhắn tin, bạn phải sử dụng trường thread.name
.
Nếu không tìm thấy chuỗi nào phù hợp, bạn có thể chỉ định
liệu một thư sẽ bắt đầu một chuỗi mới hay không đăng được bằng cách cài đặt
messageReplyOption
.
Nếu messageReplyOption
đã đặt, bạn cũng phải đặt thread.name
hoặc thread.threadKey
.
Dưới đây là cách bắt đầu hoặc trả lời một chuỗi thư 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 apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # 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ã, thay thế
SPACE
bằng tên không gian, mà bạn có thể lấy từ Phương thứcspaces.list
trong API Chat hoặc qua URL của một 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 phiên bản của
Message
nêu chi tiết tin nhắn được gửi.
Đặt tên cho thông báo
Phần này giải thích cách đặt tên cho thông báo bằng cách đặt ID tùy chỉnh cho
. Bạn có thể sử dụng mã tuỳ chỉnh để nhận, cập nhật hoặc xoá tin nhắn. Mã tuỳ chỉnh
cho phép bạn chỉ định một thông báo mà không cần lưu trữ mã nhận dạng do hệ thống chỉ định
tên tài nguyên của thông báo (biểu thị trong trường name
). Tài nguyên
được tạo trong
nội dung phản hồi
khi bạn tạo thông báo.
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. Nếu đã đặt tên cho thông báo, bạn có thể thay thế
giá trị của {message}
bằng mã tuỳ chỉnh.
Để đặ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ưngcustom-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.
Dưới đây là cách gửi thư bằng mã tuỳ chỉnh:
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 apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # 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-NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
Trong mã, thay thế các nội dung sau:
SPACE
: Mã nhận dạng của không gian mà bạn muốn truy cập đăng thông báo mà bạn có thể nhận được từ Phương thứcspaces.list
trong API Chat hoặc qua URL của một không gian.NAME
: Tên tuỳ chỉnh cho thông báo.
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 phiên bản của
Message
.
Thêm tiện ích tương tác ở cuối thư
Bạn có thể tùy chọn thêm tin nhắn bằng 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 một tin nhắn. Bạn có thể sử dụng các tiện ích 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ư sau:
- Đá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[]
đối tượng trong thông báo và chỉ định một hoặc nhiều
AccessoryWidgets
mà bạn muốn đưa vào. Mọi người trong không gian đều phải nhìn thấy tin nhắn này
(Bạn không thể thêm tiện ích phụ kiện vào tin nhắn riêng tư).
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.
Mã mẫu sau đây cho thấy JSON của thông báo này. Khi người dùng nhấp vào
một trong các nút, tương tác sẽ kích hoạt chức năng tương ứng (chẳng hạn như
doUpvote
) xử lý mức phân loại.
"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 ở chế độ riêng tư
Các ứng dụng trong Chat có thể gửi tin nhắn văn bản và tin nhắn thẻ ở chế độ riêng tư để
tin nhắn chỉ hiển thị cho một người dùng trong không gian. Để gửi thư ở chế độ riêng tư,
bạn chỉ định trường privateMessageViewer
trong thông báo. Chỉ
Các ứng dụng nhắn tin có thể gửi tin nhắn riêng tư. Để gửi tin nhắn riêng tư
không đồng bộ, bạn phải sử dụng xác thực ứng dụng.
Để biết thông tin chi tiết, hãy xem bài viết Gửi tin nhắn riêng tư đến Google Chat người dùng.
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.
Chủ đề có liên quan
- Định dạng một thư.
- Xem chi tiết về tin nhắn.
- Liệt kê tin nhắn trong không gian.
- Cập nhật tin nhắn.
- Xoá thư.
- Xác định người dùng trong tin nhắn trong Google Chat.
- Gửi tin nhắn đến Google Chat bằng webhook đến.