В этом руководстве описаны различные способы отправки сообщений приложениями Google Chat:
- Отправляйте текстовые сообщения и карточные сообщения в режиме реального времени, отвечая на действия пользователя.
- Отправляйте текстовые и карточные сообщения асинхронно, вызывая метод
create
ресурсаMessage
. - Начните ветку сообщений или ответьте на нее.
- Отправьте сообщение и назовите его.
Ресурс Message
представляет собой текстовое сообщение или карточку в Google Chat. Вы можете create
, get
, update
или delete
сообщение в Google Chat API, вызвав соответствующие методы. Дополнительную информацию о текстовых сообщениях и карточках см. в разделе Обзор сообщений Google Chat .
Максимальный размер сообщения (включая любой текст и карточки) — 32 000 байт. Если сообщение превышает этот размер, ваше приложение Chat может вместо этого отправить несколько сообщений.
Вместо вызова метода create
ресурса Message
API Google Chat для асинхронной отправки текстового сообщения или сообщения-карточки приложения Google Chat также могут создавать сообщения для ответа на действия пользователя в режиме реального времени. Ответы на взаимодействие с пользователем не требуют аутентификации и поддерживают другие типы сообщений, включая интерактивные диалоги и предварительный просмотр ссылок. Подробную информацию см. в разделе Получение и ответ на взаимодействие с вашим приложением Google Chat .
Предварительные условия
Node.js
- Приложение Google Chat. Чтобы создать приложение Chat с использованием службы HTTP, выполните это краткое руководство .
- Для приложения Chat настроена авторизация для отправки асинхронных сообщений. Для отправки сообщений в режиме реального времени не требуется настройка авторизации.
- Отправка текстового сообщения поддерживает оба следующих метода авторизации:
- Аутентификация пользователя с областью авторизации
chat.messages.create
илиchat.messages
. - Аутентификация приложения с областью авторизации
chat.bot
.
- Аутентификация пользователя с областью авторизации
- Для отправки карточного сообщения требуется аутентификация приложения с областью авторизации
chat.bot
.
- Отправка текстового сообщения поддерживает оба следующих метода авторизации:
Питон
- Приложение Google Chat. Чтобы создать приложение Chat с использованием службы HTTP, выполните это краткое руководство .
- Для приложения Chat настроена авторизация для отправки асинхронных сообщений. Для отправки сообщений в режиме реального времени не требуется настройка авторизации.
- Отправка текстового сообщения поддерживает оба следующих метода авторизации:
- Аутентификация пользователя с областью авторизации
chat.messages.create
илиchat.messages
. - Аутентификация приложения с областью авторизации
chat.bot
.
- Аутентификация пользователя с областью авторизации
- Для отправки карточного сообщения требуется аутентификация приложения с областью авторизации
chat.bot
.
- Отправка текстового сообщения поддерживает оба следующих метода авторизации:
Скрипт приложений
- Приложение Google Chat. Чтобы создать приложение Chat в Apps Script, выполните это краткое руководство .
- Для приложения Chat настроена авторизация для отправки асинхронных сообщений. Для отправки сообщений в режиме реального времени не требуется настройка авторизации.
- Отправка текстового сообщения поддерживает оба следующих метода авторизации:
- Аутентификация пользователя с областью авторизации
chat.messages.create
илиchat.messages
. - Аутентификация приложения с областью авторизации
chat.bot
.
- Аутентификация пользователя с областью авторизации
- Для отправки карточного сообщения требуется аутентификация приложения с областью авторизации
chat.bot
.
- Отправка текстового сообщения поддерживает оба следующих метода авторизации:
Отправлять текстовые сообщения
В этом разделе описывается, как отправлять текстовые сообщения следующими двумя способами:
- Отправляйте текстовые сообщения в режиме реального времени, отвечая на действия пользователя.
- Отправьте текстовое сообщение, вызвав асинхронный вызов Google Chat API.
Отправьте текстовое сообщение в режиме реального времени
В этом примере ваше приложение чата создает и отправляет текстовое сообщение всякий раз, когда оно добавляется в пространство. Чтобы узнать о лучших практиках адаптации пользователей, ознакомьтесь со статьей «Привлеките людей и пространства к работе с помощью полезной адаптации» .
Чтобы отправить текстовое сообщение, когда пользователь добавляет ваше приложение Chat в пространство, ваше приложение Chat реагирует на событие взаимодействия ADDED_TO_SPACE
. Чтобы ответить на события взаимодействия ADDED_TO_SPACE
текстовым сообщением, используйте следующий код:
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`.'
});
}
};
Скрипт приложений
/**
* 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`.'
}
}
Пример кода возвращает следующее текстовое сообщение:
Отправка текстового сообщения асинхронно
В следующем разделе объясняется, как отправить текстовое сообщение асинхронно с аутентификацией приложения и аутентификацией пользователя.
Чтобы отправить текстовое сообщение, передайте в запросе следующее:
- При аутентификации через приложение укажите область авторизации
chat.bot
. При аутентификации пользователя укажите областьchat.messages.create
. - Вызовите метод
create
для ресурсаMessage
.
Отправьте текстовое сообщение с аутентификацией приложения
Вот как отправить текстовое сообщение с аутентификацией приложения :
Питон
- В своем рабочем каталоге создайте файл с
chat_create_text_message_app.py
. Включите следующий код в
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)
В коде замените
SPACE
именем пространства, которое можно получить с помощью методаspaces.list()
в Chat API или из URL-адреса пространства.В своем рабочем каталоге соберите и запустите пример:
python3 chat_create_text_message_app.py
API чата возвращает экземпляр Message
с подробным описанием отправленного сообщения.
Отправьте текстовое сообщение с аутентификацией пользователя
Вот как отправить текстовое сообщение с аутентификацией пользователя :
Питон
- В своем рабочем каталоге создайте файл с
chat_create_text_message_user.py
. Включите следующий код в
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()
В коде замените
SPACE
именем пространства, которое можно получить с помощью методаspaces.list()
в Chat API или из URL-адреса пространства.В своем рабочем каталоге соберите и запустите пример:
python3 chat_create_text_message_user.py
API чата возвращает экземпляр Message
с подробным описанием отправленного сообщения.
Отправлять карточные сообщения
В этом разделе описывается, как отправлять карточные сообщения следующими двумя способами:
- Отправьте карточное сообщение в режиме реального времени, отвечая на взаимодействие с пользователем.
- Отправьте карточное сообщение, вызвав асинхронный вызов Google Chat API.
Отправьте карточное сообщение в режиме реального времени
Приложения чата могут создавать карточные сообщения в ответ на взаимодействие с пользователем, например, когда пользователь отправляет приложению чата сообщение или добавляет приложение чата в пространство. Дополнительные сведения о реагировании на взаимодействия с пользователем см. в разделе Получение событий взаимодействия с приложением Chat и ответ на них .
В этом примере пользователь отправляет сообщение в приложение чата, а приложение чата отвечает, отправляя карточное сообщение, в котором отображается имя пользователя и изображение аватара:
Node.js
Питон
Скрипт приложений
В этом примере отправляется карточное сообщение, возвращая card JSON . Вы также можете использовать службу карточек Apps Script .
Отправка карточного сообщения асинхронно
Чтобы отправить сообщение с карточкой , передайте в запросе следующее:
- При аутентификации через приложение укажите область авторизации
chat.bot
. Вы не можете отправить карточное сообщение с аутентификацией пользователя. - Вызовите метод
create
для ресурсаMessage
.
Ниже приведен пример сообщения карты:
Вот как отправить карточное сообщение с аутентификацией приложения:
Питон
- В своем рабочем каталоге создайте файл с
chat_create_card_message.py
. Включите следующий код в
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)
В коде замените
SPACE
именем пространства, которое можно получить с помощью методаspaces.list
в Chat API или из URL-адреса пространства.В своем рабочем каталоге соберите и запустите пример:
python3 chat_create_card_message.py
Начать ветку сообщений или ответить на нее
Чтобы запустить цепочку сообщений, отправьте сообщение и оставьте thread.name
пустым; Google Chat заполняет его при создании темы. При необходимости, чтобы настроить имя потока, укажите поле thread.threadKey
.
Чтобы ответить в поток сообщений, отправьте сообщение, в котором указано threadKey
или name
потока. Если цепочка была создана человеком или другим приложением чата, необходимо использовать поле thread.name
.
Если подходящая цепочка не найдена, вы можете указать, должно ли сообщение начинать новую цепочку или не отправляться, установив поле messageReplyOption
.
Если установлен messageReplyOption
, необходимо также установить thread.name
или thread.threadKey
.
Вот как запустить поток или ответить на него, используя поле threadKey
, определенное как nameOfThread
:
Питон
- В своем рабочем каталоге создайте файл с
chat_create_message_thread.py
. Включите следующий код в
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)
В коде замените
SPACE
именем пространства, которое можно получить с помощью методаspaces.list
в Chat API или из URL-адреса пространства.В своем рабочем каталоге соберите и запустите пример:
python3 chat_create_message_thread.py
API чата возвращает экземпляр Message
с подробным описанием отправленного сообщения.
Назовите сообщение
В этом разделе объясняется, как присвоить сообщению имя, задав для него собственный идентификатор. Вы можете использовать собственные идентификаторы для получения, обновления или удаления сообщений. Пользовательские идентификаторы позволяют указать сообщение без необходимости сохранять назначенный системой идентификатор из имени ресурса сообщения (представленного в поле name
). Имя ресурса генерируется в теле ответа при создании сообщения.
Например, чтобы получить сообщение с помощью метода get()
, вы используете имя ресурса, чтобы указать, какое сообщение нужно получить. Имя ресурса форматируется как spaces/{space}/messages/{message}
, где {message}
представляет собой назначенный системой идентификатор. Если вы дали сообщению имя, вы можете заменить значение {message}
на собственный идентификатор.
Чтобы назвать сообщение, укажите собственный идентификатор в поле messageId
при создании сообщения. Поле messageId
задает значение поля clientAssignedMessageId
ресурса Message
.
Вы можете назвать сообщение только при его создании. Вы не можете присвоить имя или изменить собственный идентификатор для существующих сообщений. Пользовательский идентификатор должен соответствовать следующим требованиям:
- Начинается с
client-
. Например,client-custom-name
является допустимым пользовательским идентификатором, аcustom-name
— нет. - Содержит до 63 символов и только строчные буквы, цифры и дефисы.
- Уникальна в пространстве. Приложение чата не может использовать один и тот же собственный идентификатор для разных сообщений.
Вот как отправить сообщение с собственным идентификатором:
Питон
- В своем рабочем каталоге создайте файл с
chat_create_named_message.py
. Включите следующий код в
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)
В коде замените следующее:
-
SPACE
: идентификатор пространства, в котором вы хотите опубликовать сообщение, который можно получить с помощью методаspaces.list
в Chat API или из URL-адреса пространства. -
NAME
: произвольное имя сообщения.
-
В своем рабочем каталоге соберите и запустите пример:
python3 chat_create_named_message.py
Chat API возвращает экземпляр Message
.
Добавляйте интерактивные виджеты внизу сообщения
При желании вы можете добавлять сообщения с помощью дополнительных виджетов . Дополнительные виджеты появляются после любого текста или карточек в сообщении. Вы можете использовать эти виджеты, чтобы предлагать пользователям взаимодействовать с вашим сообщением разными способами, включая следующие:
- Оцените точность или удовлетворенность сообщения.
- Сообщите о проблеме с сообщением или приложением чата.
- Откройте ссылку на связанный контент, например документацию.
- Отклоняйте или откладывайте похожие сообщения из приложения «Чат» на определенный период времени.
Чтобы добавить дополнительные виджеты, включите в сообщение объект accessoryWidgets[]
и укажите один или несколько AccessoryWidgets
, которые вы хотите включить. Сообщение должно быть видно всем в группе (в личные сообщения нельзя добавлять дополнительные виджеты).
На следующем изображении показано приложение Chat, которое добавляет к текстовому сообщению дополнительные виджеты, чтобы пользователи могли оценить свое взаимодействие с приложением Chat.
В следующем примере кода показан JSON для этого сообщения. Когда пользователь нажимает одну из кнопок, взаимодействие запускает соответствующую функцию (например, doUpvote
), которая обрабатывает рейтинг.
"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",
}
}
}
]
}
}
]
Отправляйте сообщения лично
Приложения чата могут отправлять текстовые и карточные сообщения конфиденциально, так что сообщение будет видно только одному пользователю в этом пространстве. Чтобы отправить сообщение конфиденциально, вы указываете в сообщении поле privateMessageViewer
. Только приложения чата могут отправлять личные сообщения. Чтобы отправить личное сообщение асинхронно, вы должны использовать аутентификацию приложения.
Подробную информацию см. в разделе Отправка личных сообщений пользователям Google Chat .
Устранение неполадок
Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.
Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Информацию о просмотре, отладке и исправлении ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .
похожие темы
- Отформатируйте сообщение .
- Получите подробную информацию о сообщении .
- Список сообщений в пространстве .
- Обновить сообщение .
- Удалить сообщение .
- Идентифицируйте пользователей в сообщениях Google Chat .
- Отправляйте сообщения в Google Chat с помощью входящих веб-перехватчиков .