Отправьте сообщение с помощью Google Chat API

В этом руководстве объясняется, как вызвать метод messages.create() Google Chat API, чтобы выполнить любое из следующих действий:

  • Отправляйте сообщения, содержащие текст, карточки и интерактивные виджеты.
  • Отправляйте сообщения лично конкретному пользователю чата.
  • Начните ветку сообщений или ответьте на нее.
  • Назовите сообщение, чтобы его можно было указать в других запросах Chat API.

Помимо вызова метода messages.create() , приложения чата могут создавать и отправлять сообщения в ответ на действия пользователя, например публиковать приветственное сообщение после того, как пользователь добавляет приложение чата в пространство. При ответе на взаимодействие приложения чата могут использовать другие типы функций обмена сообщениями, включая интерактивные диалоги и интерфейсы предварительного просмотра ссылок. Чтобы ответить пользователю, приложение Chat возвращает сообщение синхронно, без вызова API Chat. Подробнее об отправке сообщений в ответ на взаимодействие см. в разделе Получение и ответ на взаимодействие с помощью приложения Google Chat .

Как Chat отображает и атрибутирует сообщения, созданные с помощью Chat API

Вы можете вызвать метод messages.create() используя аутентификацию приложения и аутентификацию пользователя . Chat атрибутирует отправителя сообщения по-разному в зависимости от используемого типа аутентификации.

Когда вы проходите аутентификацию в приложении Chat, приложение Chat отправляет сообщение.

Вызов метода messages.create() с аутентификацией приложения.
Рисунок 1. При аутентификации приложения приложение Chat отправляет сообщение. Чтобы отметить, что отправитель не является человеком, рядом с именем Chat отображается App .

Когда вы проходите аутентификацию как пользователь, приложение Chat отправляет сообщение от имени пользователя. Chat также связывает приложение Chat с сообщением, отображая его имя.

Вызов метода messages.create() с аутентификацией пользователя.
Рисунок 2. При аутентификации пользователя пользователь отправляет сообщение, а Chat отображает имя приложения Chat рядом с именем пользователя.

Тип аутентификации также определяет, какие функции и интерфейсы обмена сообщениями можно включить в сообщение. Благодаря аутентификации приложений приложения чата могут отправлять сообщения, содержащие форматированный текст, интерфейсы на основе карточек и интерактивные виджеты. Поскольку пользователи чата могут отправлять в своих сообщениях только текст, вы можете включать текст только при создании сообщений с использованием аутентификации пользователя. Дополнительную информацию о функциях обмена сообщениями, доступных для Chat API, см. в обзоре сообщений Google Chat .

В этом руководстве объясняется, как использовать любой тип аутентификации для отправки сообщения с помощью Chat API.

Предварительные условия

Питон

  • Python 3.6 или выше
  • Инструмент управления пакетами pip
  • Новейшие клиентские библиотеки Google. Чтобы установить или обновить их, выполните следующую команду в интерфейсе командной строки:
    pip3 install --upgrade google-api-python-client google-auth-oauthlib

Отправка текстового сообщения от имени пользователя

В этом разделе объясняется, как отправлять сообщения от имени пользователя с использованием аутентификации пользователя . При аутентификации пользователя содержимое сообщения может содержать только текст и не должно включать функции обмена сообщениями, доступные только для приложений чата, включая интерфейсы карточек и интерактивные виджеты.

Сообщение отправлено с аутентификацией пользователя
Рисунок 3. Приложение Chat отправляет текстовое сообщение от имени пользователя.

Чтобы вызвать messages.create() с использованием аутентификации пользователя, необходимо указать в запросе следующие поля:

  • Область авторизации , поддерживающая аутентификацию пользователя для этого метода. В следующем примере используется область chat.messages.create .
  • Ресурс Space , в котором вы хотите разместить сообщение. Аутентифицированный пользователь должен быть участником пространства.
  • Ресурс Message , который необходимо создать. Чтобы определить содержание сообщения, необходимо включить text поле.

По желанию вы можете включить следующее:

Чтобы отправить текстовое сообщение от имени пользователя, выполните следующие действия:

Питон

  1. В своем рабочем каталоге создайте файл с chat_create_message_user.py .

  2. Включите следующий код в 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-адресу пространства.

  3. В своем рабочем каталоге соберите и запустите пример:

    python3 chat_create_message_user.py

  4. Если будет предложено указать URL-адрес, откройте URL-адрес, чтобы авторизовать приложение Chat в зависимости от области, которую вы использовали в своем запросе.

Приложение Chat создает сообщение, и прошедший проверку подлинности пользователь публикует его в пространстве. В интерфейсе командной строки Chat API возвращает экземпляр нового ресурса Message .

Отправьте сообщение через приложение чата

В этом разделе объясняется, как отправлять сообщения, содержащие текст, карточки и интерактивные дополнительные виджеты, с использованием аутентификации приложения .

Сообщение отправлено с аутентификацией приложения
Рис. 4. Приложение Chat отправляет сообщение с текстом, карточкой и дополнительной кнопкой.

Чтобы вызвать messages.create() с использованием аутентификации приложения, необходимо указать в запросе следующие поля:

  • Область авторизации chat.bot .
  • Ресурс Space , в котором вы хотите разместить сообщение. Приложение Chat должно быть участником пространства.
  • Ресурс Message , который необходимо создать. Чтобы определить содержимое сообщения, вы можете включить форматированный текст ( text ), один или несколько интерфейсов карты ( cardsV2 ) или оба.

По желанию вы можете включить следующее:

Максимальный размер сообщения (включая любой текст и карточки) — 32 000 байт. Чтобы отправить сообщение, размер которого превышает этот размер, ваше приложение Chat должно вместо этого отправить несколько сообщений.

Чтобы отправить сообщение, опубликованное как приложение Chat, содержащее текст, карточку и нажимаемую кнопку внизу сообщения, выполните следующие действия:

Питон

  1. В своем рабочем каталоге создайте файл с chat_create_message_app.py .

  2. Включите следующий код в 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-адресу пространства.

  3. В своем рабочем каталоге соберите и запустите пример:

    python3 chat_create_message_app.py

Приложение Chat создает и публикует сообщение в группе. В интерфейсе командной строки Chat API возвращает экземпляр нового ресурса Message .

Добавляйте интерактивные виджеты внизу сообщения

В примере кода из предыдущего раздела сообщение приложения Chat отображает интерактивную кнопку в нижней части сообщения, известную как дополнительный виджет . Дополнительные виджеты появляются после любого текста или карточек в сообщении. Вы можете использовать эти виджеты, чтобы предлагать пользователям взаимодействовать с вашим сообщением разными способами, включая следующие:

  • Оцените точность или удовлетворенность сообщения.
  • Сообщите о проблеме с сообщением или приложением чата.
  • Откройте ссылку на связанный контент, например документацию.
  • Отклоняйте или откладывайте похожие сообщения из приложения «Чат» на определенный период времени.

Чтобы добавить вспомогательные виджеты, включите поле accessoryWidgets[] в тело вашего запроса и укажите один или несколько виджетов, которые вы хотите включить.

На следующем изображении показано приложение Chat, которое добавляет к текстовому сообщению дополнительные виджеты, чтобы пользователи могли оценить свое взаимодействие с приложением Chat.

Аксессуарный виджет.
Рис. 5. Сообщение приложения 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» .