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.
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.
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
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 phương thức 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 dành 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
Python
- Doanh nghiệp Tài khoản Google Workspace có quyền truy cập vào Google Chat.
- Python 3.6 trở lên
- Công cụ quản lý gói pip
- Thư viện ứng dụng mới nhất của Google. Cách cài đặt hoặc cập nhật các tính năng này:
chạy lệnh sau trong giao diện dòng lệnh:
pip3 install --upgrade google-api-python-client google-auth-oauthlib
- 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.
- Tạo thông tin xác thực truy cập dựa trên cách bạn muốn xác thực trong API Google Chat
yêu cầu:
- Cách xác thực là người dùng Chat:
tạo mã ứng dụng OAuth
thông tin xác thực và 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 địa phương của bạn. - Cách xác thực là ứng dụng Chat:
tạo tài khoản dịch vụ
thông tin xác thực và lưu thông tin đăng nhập dưới dạng tệp JSON có tên
credentials.json
.
- Cách xác thực là người dùng Chat:
tạo mã ứng dụng OAuth
thông tin xác thực và 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.
- Phòng Google Chat tại đó người dùng đã xác thực hoặc gọi cho ứng dụng Chat là một thành viên. Để xác thực là ứng dụng Chat, hãy thêm Ứng dụng nhắn tin với không gian.
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 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àotext
.
Nếu muốn, bạn có thể thêm những thông tin sau:
- Trường
messageId
, cho phép bạn đặt tên cho 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 chuỗi tin nhắn. Nếu không gian sử dụng luồng, trường này sẽ bị bỏ qua.
Để thay mặt người dùng gửi tin nhắn văn bản, hãy làm theo các bước sau:
Python
- Trong thư mục đang làm việc, hãy tạo một tệp có tên
chat_create_message_user.py
. Đưa mã sau vào
chat_create_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', # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstusermessage', # The text message to create. body={ '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>.' } ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
Thay thế
SPACE
bằng mã nhận dạng của không gianname
. Bạn có thể lấy ID bằng cách gọi hàm Phương thứcspaces.list()
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_user.py
Nếu được nhắc với một URL, hãy mở URL đó để cấp quyền Ứng dụng trong Chat dựa trên phạm vi mà bạn dùng trong của bạn.
Ứng dụng Chat tạo tin nhắn và
người dùng đăng tin nhắn trong không gian. Trong giao diện dòng lệnh,
API Chat trả về phiên bản của phiên bản mới
Tài nguyên Message
.
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 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:
- Trường
accessoryWidgets
cần đưa vào các nút tương tác ở cuối thông báo. - Trường
privateMessageViewer
để gửi thư một cách riêng tư cho người dùng được chỉ định. - Trường
messageId
, cho phép bạn đặt tên cho 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 chuỗi tin nhắn. Nếu không gian sử dụng luồng, trường này sẽ bị bỏ qua.
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ư.
Để gửi tin nhắn được đăng dưới dạng ứng dụng Chat có chứa tin nhắn văn bản, thẻ và nút có thể nhấp ở cuối thông báo, hãy thực hiện các bước sau:
Python
- Trong thư mục đang làm việc, hãy tạo một tệp có tên
chat_create_message_app.py
. Đưa mã sau vào
chat_create_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) # Specify the Chat space where the message is posted. Obtain the ID # from the resource name, or from the space's URL. SPACE = 'spaces/SPACE' # Create a Chat message. result = chat.spaces().messages().create( # The Chat space. parent=SPACE, # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstappmessage', # The message to create with text, a card, and a button at the # bottom of the message. body= { 'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.', 'cardsV2': [{ 'cardId': 'myCardId', 'card': { 'header': { 'title': 'About this message', 'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg', 'imageType': 'CIRCLE' }, "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." }}, { "textParagraph": { "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.' }} ] } ]} }], "accessoryWidgets": [ { "buttonList": { "buttons": [ { "text": "View documentation", "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.", "icon": { "material_icon": { "name": "link" } }, "onClick": { "openLink": { "url": "https://developers.google.com/workspace/chat/create-messages" } } } ] } } ] } ).execute() print(result)
Thay thế
SPACE
bằng mã nhận dạng của không gianname
. Bạn có thể lấy ID bằng cách gọi hàm Phương thứcspaces.list()
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_app.py
Ứng dụng Chat tạo và đăng tin nhắn trong
. Trong giao diện dòng lệnh, API Chat trả về
của phiên bản mới
Tài nguyên Message
.
Thêm tiện ích tương tác ở cuối thư
Trong mã mẫu ở phần trước, thông tin 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.
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"
}
}
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:
Bắt đầu hoặc trả lời trong một chuỗi tin nhắn
Đối với các 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 bả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ỉ địnhthreadKey
mà bạn đã tạo. Nếu không, bạn phải sử dụngname
của chuỗi. - Chỉ định tham số truy vấn
messageReplyOption
.
Tệp JSON sau đây cho thấy ví dụ về nội dung yêu cầu cho một tin nhắn văn bản
bắt đầu hoặc trả lời chuỗi bằng khoá helloWorldThread
:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
Đặ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ư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.
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
- Sử dụng Trình tạo thẻ để thiết kế và xem trước tin nhắn trên thẻ JSON cho ứng dụng trong 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á 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.