В этом руководстве объясняется, как вызвать метод messages.create()
Google Chat API, чтобы выполнить любое из следующих действий:
- Отправляйте сообщения, содержащие текст, карточки и интерактивные виджеты.
- Отправляйте сообщения лично конкретному пользователю чата.
- Начните ветку сообщений или ответьте на нее.
- Назовите сообщение, чтобы его можно было указать в других запросах Chat API.
Помимо вызова метода messages.create()
, приложения чата могут создавать и отправлять сообщения в ответ на действия пользователя, например публиковать приветственное сообщение после того, как пользователь добавляет приложение чата в пространство. При ответе на взаимодействие приложения чата могут использовать другие типы функций обмена сообщениями, включая интерактивные диалоги и интерфейсы предварительного просмотра ссылок. Чтобы ответить пользователю, приложение Chat возвращает сообщение синхронно, без вызова API Chat. Подробнее об отправке сообщений в ответ на взаимодействие см. в разделе Получение и ответ на взаимодействие с помощью приложения Google Chat .
Как Chat отображает и атрибутирует сообщения, созданные с помощью Chat API
Вы можете вызвать метод messages.create()
используя аутентификацию приложения и аутентификацию пользователя . Chat атрибутирует отправителя сообщения по-разному в зависимости от используемого типа аутентификации.
Когда вы проходите аутентификацию в приложении Chat, приложение Chat отправляет сообщение.
Когда вы проходите аутентификацию как пользователь, приложение Chat отправляет сообщение от имени пользователя. Chat также связывает приложение Chat с сообщением, отображая его имя.
Тип аутентификации также определяет, какие функции и интерфейсы обмена сообщениями можно включить в сообщение. Благодаря аутентификации приложений приложения чата могут отправлять сообщения, содержащие форматированный текст, интерфейсы на основе карточек и интерактивные виджеты. Поскольку пользователи чата могут отправлять в своих сообщениях только текст, вы можете включать текст только при создании сообщений с использованием аутентификации пользователя. Дополнительную информацию о функциях обмена сообщениями, доступных для Chat API, см. в обзоре сообщений Google Chat .
В этом руководстве объясняется, как использовать любой тип аутентификации для отправки сообщения с помощью Chat API.
Предварительные условия
Питон
- Аккаунт Google Workspace для бизнеса или предприятия с доступом к Google Chat .
- Python 3.6 или выше
- Инструмент управления пакетами pip
- Новейшие клиентские библиотеки Google. Чтобы установить или обновить их, выполните следующую команду в интерфейсе командной строки:
pip3 install --upgrade google-api-python-client google-auth-oauthlib
- Настройте свою среду:
- Создайте проект Google Cloud .
- Настройте экран согласия OAuth .
- Включите и настройте API Google Chat, указав имя, значок и описание для вашего приложения Chat.
- Создайте учетные данные доступа в зависимости от того, как вы хотите пройти аутентификацию в запросе к API Google Chat:
- Чтобы пройти аутентификацию в качестве пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде файла JSON с именем
client_secrets.json
в локальном каталоге. - Чтобы пройти аутентификацию в качестве приложения Chat, создайте учетные данные учетной записи службы и сохраните их в виде файла JSON с именем
credentials.json
.
- Чтобы пройти аутентификацию в качестве пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде файла JSON с именем
- Выберите область авторизации в зависимости от того, хотите ли вы пройти аутентификацию как пользователь или приложение Chat.
- Пространство Google Chat , участником которого является прошедший проверку подлинности пользователь или вызывающее приложение Chat. Чтобы пройти аутентификацию в качестве приложения Chat, добавьте приложение Chat в пространство .
Отправка текстового сообщения от имени пользователя
В этом разделе объясняется, как отправлять сообщения от имени пользователя с использованием аутентификации пользователя . При аутентификации пользователя содержимое сообщения может содержать только текст и не должно включать функции обмена сообщениями, доступные только для приложений чата, включая интерфейсы карточек и интерактивные виджеты.
Чтобы вызвать messages.create()
с использованием аутентификации пользователя, необходимо указать в запросе следующие поля:
- Область авторизации , поддерживающая аутентификацию пользователя для этого метода. В следующем примере используется область
chat.messages.create
. - Ресурс
Space
, в котором вы хотите разместить сообщение. Аутентифицированный пользователь должен быть участником пространства. - Ресурс
Message
, который необходимо создать. Чтобы определить содержание сообщения, необходимо включитьtext
поле.
По желанию вы можете включить следующее:
- Поле
messageId
, позволяющее назвать сообщение, которое будет использоваться в других запросах API. - Поля
thread.threadKey
иmessageReplyOption
для запуска потока или ответа на него . Если пространство не использует потоки, это поле игнорируется.
Чтобы отправить текстовое сообщение от имени пользователя, выполните следующие действия:
Питон
- В своем рабочем каталоге создайте файл с
chat_create_message_user.py
. Включите следующий код в
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()
Замените
SPACE
идентификатором из поляname
пространства. Вы можете получить идентификатор, вызвав методspaces.list()
или по URL-адресу пространства.В своем рабочем каталоге соберите и запустите пример:
python3 chat_create_message_user.py
Если будет предложено указать URL-адрес, откройте URL-адрес, чтобы авторизовать приложение Chat в зависимости от области, которую вы использовали в своем запросе.
Приложение Chat создает сообщение, и прошедший проверку подлинности пользователь публикует его в пространстве. В интерфейсе командной строки Chat API возвращает экземпляр нового ресурса Message
.
Отправьте сообщение через приложение чата
В этом разделе объясняется, как отправлять сообщения, содержащие текст, карточки и интерактивные дополнительные виджеты, с использованием аутентификации приложения .
Чтобы вызвать messages.create()
с использованием аутентификации приложения, необходимо указать в запросе следующие поля:
- Область авторизации
chat.bot
. - Ресурс
Space
, в котором вы хотите разместить сообщение. Приложение Chat должно быть участником пространства. - Ресурс
Message
, который необходимо создать. Чтобы определить содержимое сообщения, вы можете включить форматированный текст (text
), один или несколько интерфейсов карты (cardsV2
) или оба.
По желанию вы можете включить следующее:
- Поле
accessoryWidgets
для включения интерактивных кнопок внизу сообщения . - Поле
privateMessageViewer
для частной отправки сообщения указанному пользователю. - Поле
messageId
, позволяющее назвать сообщение, которое будет использоваться в других запросах API. - Поля
thread.threadKey
иmessageReplyOption
для запуска потока или ответа на него . Если пространство не использует потоки, это поле игнорируется.
Максимальный размер сообщения (включая любой текст и карточки) — 32 000 байт. Чтобы отправить сообщение, размер которого превышает этот размер, ваше приложение Chat должно вместо этого отправить несколько сообщений.
Чтобы отправить сообщение, опубликованное как приложение Chat, содержащее текст, карточку и нажимаемую кнопку внизу сообщения, выполните следующие действия:
Питон
- В своем рабочем каталоге создайте файл с
chat_create_message_app.py
. Включите следующий код в
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)
Замените
SPACE
идентификатором из поляname
пространства. Вы можете получить идентификатор, вызвав методspaces.list()
или по URL-адресу пространства.В своем рабочем каталоге соберите и запустите пример:
python3 chat_create_message_app.py
Приложение Chat создает и публикует сообщение в группе. В интерфейсе командной строки Chat API возвращает экземпляр нового ресурса Message
.
Добавляйте интерактивные виджеты внизу сообщения
В примере кода из предыдущего раздела сообщение приложения Chat отображает интерактивную кнопку в нижней части сообщения, известную как дополнительный виджет . Дополнительные виджеты появляются после любого текста или карточек в сообщении. Вы можете использовать эти виджеты, чтобы предлагать пользователям взаимодействовать с вашим сообщением разными способами, включая следующие:
- Оцените точность или удовлетворенность сообщения.
- Сообщите о проблеме с сообщением или приложением чата.
- Откройте ссылку на связанный контент, например документацию.
- Отклоняйте или откладывайте похожие сообщения из приложения «Чат» на определенный период времени.
Чтобы добавить вспомогательные виджеты, включите поле accessoryWidgets[]
в тело вашего запроса и укажите один или несколько виджетов, которые вы хотите включить.
На следующем изображении показано приложение Chat, которое добавляет к текстовому сообщению дополнительные виджеты, чтобы пользователи могли оценить свое взаимодействие с приложением Chat.
Ниже показано тело запроса, который создает текстовое сообщение с двумя дополнительными кнопками. Когда пользователь нажимает кнопку, соответствующая функция (например, 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",
}
}
}
]
}
}
]
Отправить сообщение лично
Приложения чата могут отправлять сообщения конфиденциально, чтобы сообщение было видно только определенному пользователю в пространстве. Когда приложение чата отправляет личное сообщение, в сообщении отображается метка, уведомляющая пользователя о том, что сообщение видно только ему.
Чтобы отправить сообщение конфиденциально с помощью Chat API, укажите поле privateMessageViewer
в тексте вашего запроса. Чтобы указать пользователя, вы устанавливаете значение ресурса User
, который представляет пользователя Chat. Вы также можете использовать поле name
ресурса User
, как показано в следующем примере:
{
"text": "Hello private world!",
"privateMessageViewer": {
"name": "users/USER_ID"
}
}
Замените USER_ID
уникальным идентификатором пользователя, например 12345678987654321
или hao@cymbalgroup.com
. Дополнительную информацию об указании пользователей см. в разделе Идентификация и указание пользователей Google Chat .
Чтобы отправить сообщение в частном порядке, в запросе необходимо опустить следующее:
Начать или ответить в теме
Для пространств, использующих потоки , вы можете указать, будет ли новое сообщение запускать поток или отвечать на существующий поток.
По умолчанию сообщения, созданные с помощью Chat API, начинают новую цепочку. Чтобы помочь вам идентифицировать цепочку и ответить на нее позже, вы можете указать ключ цепочки в своем запросе:
- В теле запроса укажите поле
thread.threadKey
. - Укажите параметр запроса
messageReplyOption
чтобы определить, что произойдет, если ключ уже существует.
Чтобы создать сообщение, отвечающее на существующую тему:
- В тексте вашего запроса включите поле
thread
. Если установлено, вы можете указать созданный вамиthreadKey
. В противном случае вы должны использоватьname
потока. - Укажите параметр запроса
messageReplyOption
.
Следующий JSON показывает пример тела запроса для текстового сообщения, которое запускает поток или отвечает на него с помощью ключа helloWorldThread
:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
Назовите сообщение
Чтобы получить или указать сообщение в будущих вызовах API, вы можете назвать сообщение, установив поле messageId
в запросе messages.create()
. Присвоение имени сообщению позволяет указать его без необходимости сохранять назначенный системой идентификатор из имени ресурса сообщения (представленного в поле name
).
Например, чтобы получить сообщение с помощью метода get()
, вы используете имя ресурса, чтобы указать, какое сообщение нужно получить. Имя ресурса форматируется как spaces/{space}/messages/{message}
, где {message}
представляет собой назначенный системой идентификатор или пользовательское имя, которое вы установили при создании сообщения.
Чтобы назвать сообщение, укажите собственный идентификатор в поле messageId
при создании сообщения. Поле messageId
задает значение поля clientAssignedMessageId
ресурса Message
.
Вы можете назвать сообщение только при его создании. Вы не можете присвоить имя или изменить собственный идентификатор для существующих сообщений. Пользовательский идентификатор должен соответствовать следующим требованиям:
- Начинается с
client-
. Например,client-custom-name
является допустимым пользовательским идентификатором, аcustom-name
— нет. - Содержит до 63 символов и только строчные буквы, цифры и дефисы.
- Уникальна в пространстве. Приложение чата не может использовать один и тот же собственный идентификатор для разных сообщений.
Устранение неполадок
Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.
Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Информацию о просмотре, отладке и исправлении ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .
Связанные темы
- Используйте конструктор карточек для разработки и предварительного просмотра карточных сообщений JSON для приложений чата.
- Форматировать сообщения .
- Получите подробную информацию о сообщении .
- Список сообщений в пространстве .
- Обновить сообщение .
- Удалить сообщение .
- Идентифицируйте пользователей в сообщениях Google Chat .
- Отправляйте сообщения в Google Chat с помощью входящих веб-перехватчиков .