В этом руководстве объясняется, как вызвать метод messages.create()
Google Chat API, чтобы выполнить любое из следующих действий:
- Отправляйте сообщения, содержащие текст, карточки и интерактивные виджеты.
- Отправляйте сообщения лично конкретному пользователю чата.
- Начните ветку сообщений или ответьте на нее.
- Назовите сообщение, чтобы его можно было указать в других запросах Chat API.
Максимальный размер сообщения (включая любой текст и карточки) — 32 000 байт. Чтобы отправить сообщение, размер которого превышает этот размер, ваше приложение Chat должно вместо этого отправить несколько сообщений.
Помимо вызова метода messages.create()
, приложения чата могут создавать и отправлять сообщения в ответ на действия пользователя, например публиковать приветственное сообщение после того, как пользователь добавляет приложение чата в пространство. При ответе на взаимодействие приложения чата могут использовать другие типы функций обмена сообщениями, включая интерактивные диалоги и интерфейсы предварительного просмотра ссылок. Чтобы ответить пользователю, приложение Chat возвращает сообщение синхронно, без вызова API Chat. Подробнее об отправке сообщений в ответ на взаимодействие см. в разделе Получение и ответ на взаимодействие с помощью приложения Google Chat .
Как Chat отображает и атрибутирует сообщения, созданные с помощью Chat API
Вы можете вызвать метод messages.create()
используя аутентификацию приложения и аутентификацию пользователя . Chat атрибутирует отправителя сообщения по-разному в зависимости от используемого типа аутентификации.
Когда вы проходите аутентификацию в приложении Chat, приложение Chat отправляет сообщение.
Когда вы проходите аутентификацию как пользователь, приложение Chat отправляет сообщение от имени пользователя. Chat также связывает приложение Chat с сообщением, отображая его имя.
Тип аутентификации также определяет, какие функции и интерфейсы обмена сообщениями можно включить в сообщение. Благодаря аутентификации приложений приложения чата могут отправлять сообщения, содержащие форматированный текст, интерфейсы на основе карточек и интерактивные виджеты. Поскольку пользователи чата могут отправлять в своих сообщениях только текст, вы можете включать текст только при создании сообщений с использованием аутентификации пользователя. Дополнительную информацию о функциях обмена сообщениями, доступных для Chat API, см. в обзоре сообщений Google Chat .
В этом руководстве объясняется, как использовать любой тип аутентификации для отправки сообщения с помощью Chat API.
Предварительные условия
Node.js
- Аккаунт Google Workspace для бизнеса или предприятия с доступом к Google Chat .
- Настройте свою среду:
- Создайте проект Google Cloud .
- Настройте экран согласия OAuth .
- Включите и настройте API Google Chat, указав имя, значок и описание для вашего приложения Chat.
- Установите облачную клиентскую библиотеку Node.js.
- Создайте учетные данные доступа в зависимости от того, как вы хотите пройти аутентификацию в запросе к API Google Chat:
- Чтобы пройти аутентификацию в качестве пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде файла JSON с именем
client_secrets.json
в локальном каталоге. - Чтобы пройти аутентификацию в качестве приложения Chat, создайте учетные данные учетной записи службы и сохраните их в виде файла JSON с именем
credentials.json
.
- Чтобы пройти аутентификацию в качестве пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде файла JSON с именем
- Выберите область авторизации в зависимости от того, хотите ли вы пройти аутентификацию как пользователь или приложение Chat.
- Пространство Google Chat , участником которого является прошедший проверку подлинности пользователь или вызывающее приложение Chat. Чтобы пройти аутентификацию в качестве приложения Chat, добавьте приложение Chat в пространство .
Питон
- Аккаунт Google Workspace для бизнеса или предприятия с доступом к Google Chat .
- Настройте свою среду:
- Создайте проект Google Cloud .
- Настройте экран согласия OAuth .
- Включите и настройте API Google Chat, указав имя, значок и описание для вашего приложения Chat.
- Установите облачную клиентскую библиотеку Python.
- Создайте учетные данные доступа в зависимости от того, как вы хотите пройти аутентификацию в запросе к API Google Chat:
- Чтобы пройти аутентификацию в качестве пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде файла JSON с именем
client_secrets.json
в локальном каталоге. - Чтобы пройти аутентификацию в качестве приложения Chat, создайте учетные данные учетной записи службы и сохраните их в виде файла JSON с именем
credentials.json
.
- Чтобы пройти аутентификацию в качестве пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде файла JSON с именем
- Выберите область авторизации в зависимости от того, хотите ли вы пройти аутентификацию как пользователь или приложение Chat.
- Пространство Google Chat , участником которого является прошедший проверку подлинности пользователь или вызывающее приложение Chat. Чтобы пройти аутентификацию в качестве приложения Chat, добавьте приложение Chat в пространство .
Ява
- Аккаунт Google Workspace для бизнеса или предприятия с доступом к Google Chat .
- Настройте свою среду:
- Создайте проект Google Cloud .
- Настройте экран согласия OAuth .
- Включите и настройте API Google Chat, указав имя, значок и описание для вашего приложения Chat.
- Установите облачную клиентскую библиотеку Java.
- Создайте учетные данные доступа в зависимости от того, как вы хотите пройти аутентификацию в запросе к API Google Chat:
- Чтобы пройти аутентификацию в качестве пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде файла JSON с именем
client_secrets.json
в локальном каталоге. - Чтобы пройти аутентификацию в качестве приложения Chat, создайте учетные данные учетной записи службы и сохраните их в виде файла JSON с именем
credentials.json
.
- Чтобы пройти аутентификацию в качестве пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде файла JSON с именем
- Выберите область авторизации в зависимости от того, хотите ли вы пройти аутентификацию как пользователь или приложение Chat.
- Пространство Google Chat , участником которого является прошедший проверку подлинности пользователь или вызывающее приложение Chat. Чтобы пройти аутентификацию в качестве приложения Chat, добавьте приложение Chat в пространство .
Скрипт приложений
- Аккаунт Google Workspace для бизнеса или предприятия с доступом к Google Chat .
- Настройте свою среду:
- Создайте проект Google Cloud .
- Настройте экран согласия OAuth .
- Включите и настройте API Google Chat, указав имя, значок и описание для вашего приложения Chat.
- Создайте автономный проект Apps Script и включите расширенную службу чата .
- В этом руководстве вы должны использовать аутентификацию пользователя или приложения . Для аутентификации в качестве приложения Chat создайте учетные данные сервисной учетной записи. Инструкции см. в разделе Аутентификация и авторизация в качестве приложения Google Chat .
- Выберите область авторизации в зависимости от того, хотите ли вы пройти аутентификацию как пользователь или приложение Chat.
- Пространство Google Chat , участником которого является прошедший проверку подлинности пользователь или вызывающее приложение Chat. Чтобы пройти аутентификацию в качестве приложения Chat, добавьте приложение Chat в пространство .
Отправьте сообщение через приложение чата
В этом разделе объясняется, как отправлять сообщения, содержащие текст, карточки и интерактивные дополнительные виджеты, с использованием аутентификации приложения .
Чтобы вызвать messages.create()
с использованием аутентификации приложения, необходимо указать в запросе следующие поля:
- Область авторизации
chat.bot
. - Ресурс
Space
, в котором вы хотите разместить сообщение. Приложение Chat должно быть участником пространства. - Ресурс
Message
, который необходимо создать. Чтобы определить содержимое сообщения, вы можете включить форматированный текст (text
), один или несколько интерфейсов карты (cardsV2
) или оба.
По желанию вы можете включить следующее:
- Поле
accessoryWidgets
для включения интерактивных кнопок внизу сообщения . - Поле
privateMessageViewer
для частной отправки сообщения указанному пользователю. - Поле
messageId
, позволяющее назвать сообщение, которое будет использоваться в других запросах API. - Поля
thread.threadKey
иmessageReplyOption
для запуска потока или ответа на него . Если пространство не использует резьбу, это поле игнорируется.
В следующем коде показан пример того, как приложение Chat может отправить сообщение, опубликованное как приложение Chat, содержащее текст, карточку и кнопку, на которую можно нажать, внизу сообщения:
Node.js
Питон
Ява
Скрипт приложений
Чтобы запустить этот пример, замените SPACE_NAME
идентификатором из поля name
пространства. Вы можете получить идентификатор, вызвав метод spaces.list()
или по URL-адресу пространства.
Добавляйте интерактивные виджеты внизу сообщения
В первом примере кода этого руководства сообщение приложения 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 .
Чтобы отправить сообщение конфиденциально, в запросе необходимо опустить следующее:
Отправка текстового сообщения от имени пользователя
В этом разделе объясняется, как отправлять сообщения от имени пользователя с использованием аутентификации пользователя . При аутентификации пользователя содержимое сообщения может содержать только текст и не должно включать функции обмена сообщениями, доступные только для приложений чата, включая интерфейсы карточек и интерактивные виджеты.
Чтобы вызвать messages.create()
с использованием аутентификации пользователя, необходимо указать в запросе следующие поля:
- Область авторизации , поддерживающая аутентификацию пользователя для этого метода. В следующем примере используется область
chat.messages.create
. - Ресурс
Space
, в котором вы хотите разместить сообщение. Аутентифицированный пользователь должен быть участником пространства. - Ресурс
Message
, который необходимо создать. Чтобы определить содержание сообщения, необходимо включитьtext
поле.
По желанию вы можете включить следующее:
- Поле
messageId
, позволяющее назвать сообщение, которое будет использоваться в других запросах API. - Поля
thread.threadKey
иmessageReplyOption
для запуска потока или ответа на него . Если пространство не использует потоки, это поле игнорируется.
В следующем коде показан пример того, как приложение чата может отправлять текстовое сообщение в заданном пространстве от имени аутентифицированного пользователя:
Node.js
Питон
Ява
Скрипт приложений
Чтобы запустить этот пример, замените SPACE_NAME
идентификатором из поля name
пространства. Вы можете получить идентификатор, вызвав метод spaces.list()
или по URL-адресу пространства.
Начать или ответить в теме
Для пространств, использующих потоки , вы можете указать, будет ли новое сообщение запускать поток или отвечать на существующий поток.
По умолчанию сообщения, созданные с помощью Chat API, начинают новую цепочку. Чтобы помочь вам идентифицировать цепочку и ответить на нее позже, вы можете указать ключ цепочки в своем запросе:
- В теле запроса укажите поле
thread.threadKey
. - Укажите параметр запроса
messageReplyOption
чтобы определить, что произойдет, если ключ уже существует.
Чтобы создать сообщение, отвечающее на существующую тему:
- В тексте вашего запроса включите поле
thread
. Если установлено, вы можете указать созданный вамиthreadKey
. В противном случае вы должны использоватьname
потока. - Укажите параметр запроса
messageReplyOption
.
В следующем коде показан пример того, как приложение чата может отправлять текстовое сообщение, которое запускает заданный поток или отвечает на него, идентифицируемый ключом данного пространства, от имени аутентифицированного пользователя:
Node.js
Питон
Ява
Скрипт приложений
Чтобы запустить этот пример, замените следующее:
-
THREAD_KEY
: существующий ключ потока в пространстве или для создания нового потока — уникальное имя потока. -
SPACE_NAME
: идентификатор из поляname
пространства. Вы можете получить идентификатор, вызвав методspaces.list()
или по URL-адресу пространства.
Назовите сообщение
Чтобы получить или указать сообщение в будущих вызовах API, вы можете назвать сообщение, установив поле messageId
в запросе messages.create()
. Присвоение имени сообщению позволяет указать сообщение без необходимости сохранять назначенный системой идентификатор из имени ресурса сообщения (представленного в поле name
).
Например, чтобы получить сообщение с помощью метода get()
, вы используете имя ресурса, чтобы указать, какое сообщение нужно получить. Имя ресурса форматируется как spaces/{space}/messages/{message}
, где {message}
представляет собой назначенный системой идентификатор или пользовательское имя, которое вы установили при создании сообщения.
Чтобы назвать сообщение, укажите собственный идентификатор в поле messageId
при создании сообщения. Поле messageId
задает значение поля clientAssignedMessageId
ресурса Message
.
Вы можете назвать сообщение только при его создании. Вы не можете присвоить имя или изменить собственный идентификатор для существующих сообщений. Пользовательский идентификатор должен соответствовать следующим требованиям:
- Начинается с
client-
. Например,client-custom-name
является допустимым пользовательским идентификатором, аcustom-name
— нет. - Содержит до 63 символов и только строчные буквы, цифры и дефисы.
- Уникальна в пространстве. Приложение чата не может использовать один и тот же собственный идентификатор для разных сообщений.
В следующем коде показан пример того, как приложение чата может отправлять текстовое сообщение с идентификатором в заданное пространство от имени аутентифицированного пользователя:
Node.js
Питон
Ява
Скрипт приложений
Чтобы запустить этот пример, замените следующее:
-
SPACE_NAME
: идентификатор из поляname
пространства. Вы можете получить идентификатор, вызвав методspaces.list()
или по URL-адресу пространства. -
MESSAGE-ID
: имя сообщения, которое начинается сcustom-
. Должно быть уникальным среди любых других имен сообщений, созданных приложением Chat в указанном пространстве.
Устранение неполадок
Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.
Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Справку по просмотру, отладке и исправлению ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .
Связанные темы
- Используйте конструктор карточек для разработки и предварительного просмотра карточных сообщений JSON для приложений чата.
- Форматировать сообщения .
- Получите подробную информацию о сообщении .
- Список сообщений в пространстве .
- Обновить сообщение .
- Удалить сообщение .
- Идентифицируйте пользователей в сообщениях Google Chat .
- Отправляйте сообщения в Google Chat с помощью входящих веб-перехватчиков .