Hướng dẫn này giải thích cách sử dụng phương thức create()
trên tài nguyên Message
của API Google Chat để 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 một tin nhắn để bạn có thể chỉ định tin nhắn đó trong các yêu cầu Chat API khác.
Kích thước tối đa của thư (bao gồm cả 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 phải gửi nhiều tin nhắn.
Ngoài việc gọi API Chat để tạo tin nhắn, các ứng dụng trong Chat còn có thể tạo và gửi tin nhắn để phản hồi hoạt động 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 một không gian. Khi phản hồi các lượt tương tác, ứng dụng Chat có thể sử dụng các loại tính năng nhắn tin khác, bao gồm cả hộp thoại tương tác và giao diện xem trước đường liên kết. Để trả lời người dùng, ứng dụng Chat sẽ trả về 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 tin nhắn phản hồi các lượt tương tác, hãy xem bài viết Nhận và phản hồi các lượt tương tác bằng ứng dụng Google Chat.
Cách Chat hiển thị và phân bổ các tin nhắn được tạo bằng API Chat
Bạn có thể gọi phương thức create()
bằng cách sử dụng quy trình xác thực ứng dụng và quy trình xác thực người dùng.
Chat sẽ phân bổ người gửi tin nhắn theo cách khác nhau tuỳ thuộc vào loại xác thực mà bạn sử dụng.
Khi bạn xác thực dưới dạng ứng dụng Chat, ứng dụng Chat sẽ gửi thông báo.
Khi bạn xác thực dưới dạng người dùng, ứng dụng Chat sẽ thay mặt người dùng gửi tin nhắn. Chat cũng phân bổ ứng dụng Chat cho thư bằng cách hiển thị tên ứng dụng.
Loại xác thực cũng xác định những tính năng và giao diện nhắn tin mà bạn có thể đưa vào thông báo. Với tính năng xác thực ứng dụng, các ứng dụng Chat 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 văn bản trong tin nhắn, nên bạn chỉ có thể đưa văn bản vào khi tạo tin nhắn bằng tính năng xác thực người dùng. Để tìm hiểu thêm về các tính năng nhắn tin có sẵn cho API Chat, hãy xem bài viết Tổng quan về tin nhắn trên 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 tin nhắn bằng API Chat.
Điều kiện tiên quyết
Node.js
- Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google Chat.
- Thiết lập môi trường:
- Tạo một dự án trên Google Cloud.
- Định cấu hình màn hình xin phép bằng OAuth.
- Bật và định cấu hình API Google Chat bằng tên, biểu tượng và nội dung mô tả cho ứng dụng Chat.
- Cài đặt Thư viện ứng dụng đám mây Node.js.
- Tạo thông tin xác thực quyền truy cập dựa trên cách bạn muốn xác thực trong yêu cầu API Google Chat:
- Để xác thực là người dùng Chat, hãy tạo thông tin đăng nhập cho mã ứng dụng OAuth rồi lưu thông tin đăng nhập dưới dạng tệp JSON có tên
client_secrets.json
vào thư mục cục bộ của bạn. - Để xác thực dưới dạng ứng dụng Chat, hãy tạo thông tin xác thực tài khoản dịch vụ và lưu thông tin xác thực dưới dạng tệp JSON có tên
credentials.json
.
- Để xác thực là người dùng Chat, hãy tạo thông tin đăng nhập cho mã ứng dụng OAuth rồi lưu thông tin đăng nhập dưới dạng tệp JSON có tên
- Chọn phạm vi uỷ quyền dựa trên việc bạn muốn xác thực là người dùng hay ứng dụng Chat.
- Một không gian Google Chat mà người dùng đã xác thực hoặc ứng dụng Chat gọi là thành viên. Để xác thực dưới dạng ứng dụng Chat, hãy thêm ứng dụng Chat vào không gian.
Python
- Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google Chat.
- Thiết lập môi trường:
- Tạo dự án trên Google Cloud.
- Định cấu hình màn hình xin phép bằng OAuth.
- Bật và định cấu hình API Google Chat bằng tên, biểu tượng và nội dung mô tả cho ứng dụng Chat.
- Cài đặt Thư viện ứng dụng Google Cloud cho Python.
- Tạo thông tin xác thực quyền truy cập dựa trên cách bạn muốn xác thực trong yêu cầu API Google Chat:
- Để xác thực là người dùng Chat, hãy tạo thông tin đăng nhập cho mã ứng dụng OAuth rồi lưu thông tin đăng nhập dưới dạng tệp JSON có tên
client_secrets.json
vào thư mục cục bộ của bạn. - Để xác thực với tư cách là ứng dụng Chat, hãy
tạo thông tin đăng nhập cho
tài khoản dịch vụ và lưu thông tin đăng nhập dưới dạng tệp JSON có tên là
credentials.json
.
- Để xác thực là người dùng Chat, hãy tạo thông tin đăng nhập cho mã ứng dụng OAuth rồi lưu thông tin đăng nhập dưới dạng tệp JSON có tên
- Chọn phạm vi uỷ quyền dựa trên việc bạn muốn xác thực dưới dạng người dùng hay ứng dụng Chat.
- Một không gian Google Chat mà người dùng đã xác thực hoặc ứng dụng Chat gọi là thành viên. Để xác thực dưới dạng ứng dụng Chat, hãy thêm ứng dụng Chat vào không gian.
Java
- Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google Chat.
- Thiết lập môi trường:
- Tạo dự án trên Google Cloud.
- Định cấu hình màn hình xin phép bằng OAuth.
- Bật và định cấu hình API Google Chat bằng tên, biểu tượng và nội dung mô tả cho ứng dụng Chat.
- Cài đặt Thư viện ứng dụng đám mây Java.
- Tạo thông tin xác thực quyền truy cập dựa trên cách bạn muốn xác thực trong yêu cầu API Google Chat:
- Để xác thực dưới dạng người dùng Chat, hãy tạo thông tin xác thực mã ứng dụng khách OAuth và lưu thông tin xác thực dưới dạng tệp JSON có tên
client_secrets.json
vào thư mục cục bộ. - Để xác thực dưới dạng ứng dụng Chat, hãy tạo thông tin xác thực tài khoản dịch vụ và lưu thông tin xác thực dưới dạng tệp JSON có tên
credentials.json
.
- Để xác thực dưới dạng người dùng Chat, hãy tạo thông tin xác thực mã ứng dụng khách OAuth và lưu thông tin xác thực dưới dạng tệp JSON có tên
- Chọn phạm vi uỷ quyền dựa trên việc bạn muốn xác thực dưới dạng người dùng hay ứng dụng Chat.
- Phòng Google Chat trong đó người dùng đã xác thực hoặc gọi ứng dụng Chat là thành viên. Để xác thực là ứng dụng Chat, hãy thêm ứng dụng Chat vào không gian.
Apps Script
- Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google Chat.
- Thiết lập môi trường:
- Tạo dự án trên Google Cloud.
- Định cấu hình màn hình xin phép bằng OAuth.
- Bật và định cấu hình API Google Chat bằng tên, biểu tượng và nội dung mô tả cho ứng dụng Chat.
- Tạo một dự án Apps Script độc lập và bật Dịch vụ trò chuyện nâng cao.
- Trong hướng dẫn này, bạn phải sử dụng quy trình xác thực người dùng hoặc ứng dụng. Để xác thực dưới dạng ứng dụng Chat, hãy tạo thông tin xác thực tài khoản dịch vụ. Để biết các bước, hãy xem bài viết Xác thực và uỷ quyền dưới dạng ứng dụng Google Chat.
- Chọn phạm vi uỷ quyền dựa trên việc bạn muốn xác thực dưới dạng người dùng hay ứng dụng Chat.
- Một không gian Google Chat mà người dùng đã xác thực hoặc ứng dụng Chat gọi là thành viên. Để xác thực là ứng dụng Chat, hãy thêm ứng dụng Chat vào không gian.
Gửi tin nhắn dưới dạng ứng dụng Chat
Phần này giải thích cách gửi thông báo chứa văn bản, thẻ và tiện ích phụ kiện tương tác bằng cách sử dụng tính năng xác thực ứng dụng.
Để gọi phương thức CreateMessage()
bằng xác thực ứng dụng, bạn phải chỉ định các trường sau trong yêu cầu:
chat.bot
phạm vi uỷ quyền.- Tài nguyên
Space
mà bạn muốn đăng thông báo. Ứng dụng Chat phải là thành viên của không gian. - Tài nguyên
Message
cần tạo. Để xác định nội dung của thông báo, bạn có thể đưa vào 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.
Bạn có thể thêm các thông tin sau đây (không bắt buộc):
- Trường
accessoryWidgets
để đưa vào các nút tương tác ở cuối thư. - Trường
privateMessageViewer
để gửi tin nhắn riêng tư cho một người dùng cụ thể. - Trường
messageId
cho phép bạn gọi tên thông báo để sử dụng trong các yêu cầu API khác. - Các trường
thread.threadKey
vàmessageReplyOption
để bắt đầu hoặc trả lời một luồng. Nếu không gian không sử dụng tính năng tạo luồng, trường này sẽ bị bỏ qua.
Mã sau đây cho thấy ví dụ về cách ứng dụng Chat có thể gửi một thông báo được đăng dưới dạng ứng dụng Chat chứa văn bản, thẻ và nút có thể nhấp ở cuối thông báo:
Node.js
Python
Java
Apps Script
Để chạy mẫu này, hãy thay thế SPACE_NAME
bằng mã nhận dạng từ trường name
của không gian. Bạn có thể lấy mã nhận dạng bằng cách gọi phương thức ListSpaces()
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, tin nhắn trong ứng dụng Chat sẽ hiển thị một nút có thể nhấp ở cuối tin nhắn, được 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 một thư. 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ông báo theo nhiều cách, bao gồm:
- Đánh giá độ chính xác hoặc mức độ hài lòng về một thông báo.
- Báo cáo vấn đề về ứng dụng Tin nhắn hoặc ứng dụng Chat.
- Mở đường liên kết đến nội dung liên quan, chẳng hạn như tài liệu.
- Bỏ qua hoặc tạm hoãn các tin nhắn tương tự trong ứ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 trường accessoryWidgets[]
vào 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 nối thêm một tin nhắn văn bản với các tiện ích phụ để người dùng có thể đánh giá trải nghiệm của họ với ứng dụng Chat.
Phần sau đây cho thấy nội dung của yêu cầu tạo một tin nhắn văn bản có hai nút phụ kiện. Khi người dùng nhấp vào một nút, hàm tương ứng (chẳng hạn như doUpvote
) sẽ xử lý hoạt động 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ư
Ứng dụng nhắn tin có thể gửi tin nhắn riêng tư để chỉ một người dùng cụ thể trong không gian mới xem được tin nhắn đó. Khi ứng dụng Chat gửi tin nhắn riêng tư, tin nhắn sẽ hiển thị một nhãn thông báo cho người dùng rằng chỉ họ mới nhìn thấy tin nhắn.
Để gửi tin nhắn riêng tư bằng API Chat, hãy chỉ định trường privateMessageViewer
trong nội dung yêu cầu. Để chỉ định người dùng, bạn đặ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 tài nguyên 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
bằng 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ề cách chỉ định người dùng, hãy xem phần Xác định và chỉ định người dùng Google Chat.
Để gửi tin nhắn riêng tư, bạn phải bỏ qua những thông tin sau trong yêu cầu:
Thay mặt người dùng gửi tin nhắn văn bản
Phần này giải thích cách thay mặt người dùng gửi thông báo bằng cách sử dụng tính năng xác thực người dùng. Khi xác thực người dùng, nội dung của tin nhắn chỉ được chứa văn bản và phải bỏ qua các tính năng nhắn tin chỉ dành cho ứng dụng Chat, bao gồm cả giao diện thẻ và tiện ích tương tác.
Để gọi phương thức CreateMessage()
bằng xác thực người dùng, bạn phải chỉ định các trường sau trong yêu cầu:
- Phạm vi uỷ quyền hỗ trợ xác thực người dùng cho phương thức này. Mẫu sau đây sử dụng phạm vi
chat.messages.create
. - Tài nguyên
Space
mà bạn muốn đăng thông báo. Người dùng được xác thực phải là thành viên của không gian. - Tài nguyên
Message
để tạo. Để xác định nội dung của thông báo, bạn phải thêm trườngtext
.
Bạn có thể thêm các thông tin sau đây (không bắt buộc):
- Trường
messageId
cho phép bạn gọi tên thông báo để sử dụng trong các yêu cầu API khác. - Các trường
thread.threadKey
vàmessageReplyOption
để bắt đầu hoặc trả lời một luồng. Nếu không gian không sử dụng tính năng tạo luồng, trường này sẽ bị bỏ qua.
Đoạn mã sau đây là ví dụ về cách ứng dụng Chat có thể thay mặt người dùng đã xác thực gửi tin nhắn văn bản trong một không gian nhất định:
Node.js
Python
Java
Apps Script
Để chạy mẫu này, hãy thay thế SPACE_NAME
bằng mã nhận dạng từ trường name
của không gian. Bạn có thể lấy mã nhận dạng bằng cách gọi phương thức ListSpaces()
hoặc từ URL của không gian.
Bắt đầu hoặc trả lời trong chuỗi tin nhắn
Đối với những không gian sử dụng chuỗi tin nhắn, bạn có thể chỉ định xem tin nhắn mới sẽ bắt đầu một chuỗi tin nhắn hay trả lời một chuỗi tin nhắn hiện có.
Theo mặc định, các tin nhắn mà bạn tạo bằng API Chat sẽ bắt đầu một chuỗi mới. Để giúp bạn xác định và trả lời luồng sau này, bạn có thể chỉ định khoá luồng trong yêu cầu:
- Trong phần nội dung của yêu cầu, hãy chỉ định trường
thread.threadKey
. - Chỉ định thông 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 một 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 đặt, bạn có thể chỉ địnhthreadKey
mà bạn đã tạo. Nếu không, bạn phải sử dụngname
của luồng. - Chỉ định tham số truy vấn
messageReplyOption
.
Mã sau đây cho thấy ví dụ về cách một ứng dụng Chat có thể gửi tin nhắn văn bản bắt đầu hoặc trả lời một chuỗi tin nhắn nhất định được xác định bằng 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
Python
Java
Apps Script
Để chạy mẫu này, hãy thay thế nội dung sau:
THREAD_KEY
: khoá chuỗi hiện có trong không gian hoặc tên duy nhất của chuỗi để tạo chuỗi mới.SPACE_NAME
: mã nhận dạng trong trườngname
của không gian. Bạn có thể lấy mã nhận dạng bằng cách gọi phương thứcListSpaces()
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 trong tương lai, 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.
Việc đặt tên cho thông báo 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 (được biểu thị trong trường name
).
Ví dụ: để truy xuất một thông báo bằng phương thức get()
, bạn sử dụng tên tài nguyên để chỉ định thông báo cần truy xuất. Tên tài nguyên được định dạng là spaces/{space}/messages/{message}
, trong đó {message}
đại diện cho mã nhận dạng do hệ thống chỉ định hoặc tên tuỳ chỉnh mà bạn đặt khi tạo thông báo.
Để đặt tên cho một thông báo, hãy chỉ định mã nhận dạng tuỳ chỉnh trong trường messageId
khi bạn tạo thông báo. Trường messageId
đặt giá trị cho trường clientAssignedMessageId
của tài nguyên Message
.
Bạn chỉ có thể đặt tên cho tin nhắn khi tạo tin nhắn. Bạn không thể đặt tên hoặc sửa đổi mã tuỳ chỉnh cho các thông báo hiện có. Mã nhận dạng 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à mã nhận dạng tuỳ chỉnh hợp lệ, nhưngcustom-name
thì không. - Chứa tối đa 63 ký tự và chỉ chứa chữ cái viết thường, số và dấu gạch nối.
- Là giá trị duy nhất trong một không gian. Ứng dụng Chat không thể sử dụng cùng một mã tuỳ chỉnh cho nhiều tin nhắn.
Mã sau đây cho thấy ví dụ về cách ứng dụng Chat có thể thay mặt cho người dùng đã xác thực gửi tin nhắn văn bản có mã nhận dạng đến một không gian nhất định:
Node.js
Python
Java
Apps Script
Để chạy mẫu này, hãy thay thế nội dung sau:
SPACE_NAME
: mã nhận dạng trong trườngname
của không gian. Bạn có thể lấy mã nhận dạng bằng cách gọi phương thứcListSpaces()
hoặc từ URL của không gian.MESSAGE-ID
: tên của thông báo bắt đầu bằngcustom-
. Tên phải riêng biệt với mọi tên tin nhắn khác do ứng dụng Chat tạo trong không gian được chỉ định.
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 Chat không hiển thị thông báo lỗi nào, nhưng ứng dụng Chat hoặc thẻ lại 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 hiển thị trong giao diện người dùng Chat, nhưng bạn có thể xem thông báo lỗi mô tả và dữ liệu nhật ký để khắc phục lỗi khi bật tính năng ghi nhật ký lỗi cho ứng dụng Chat. Để được trợ giúp xem, gỡ lỗi và khắc phục lỗi, hãy xem bài viết Khắc phục và khắc phục lỗi Google Chat.
Chủ đề có liên quan
- Sử dụng Trình tạo thẻ để thiết kế và xem trước thông báo thẻ JSON cho ứng dụng Chat.
- Định dạng 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á tin nhắn.
- Xác định người dùng trong tin nhắn trên Google Chat.
- Gửi tin nhắn tới Google Chat bằng webhook đến.