Послать сообщение

В этом руководстве описаны различные способы отправки сообщений приложениями Google Chat:

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

Ресурс Message представляет собой текстовое сообщение или карточку в Google Chat. Вы можете create , get , update или delete сообщение в Google Chat API, вызвав соответствующие методы. Дополнительную информацию о текстовых сообщениях и карточках см. в разделе Обзор сообщений Google Chat .

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

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

Node.js

Питон

  • Аккаунт Google Workspace с доступом к Google Chat .
  • Python 3.6 или выше
  • Инструмент управления пакетами pip
  • Новейшие клиентские библиотеки Google для Python. Чтобы установить или обновить их, выполните следующую команду в интерфейсе командной строки:

    pip3 install --upgrade google-api-python-client google-auth
    
  • Проект Google Cloud с включенным и настроенным API Google Chat. Инструкции см. в разделе Создание приложения Google Chat .
  • Для приложения Chat настроена авторизация для отправки асинхронных сообщений. Для отправки сообщений в режиме реального времени не требуется настройка авторизации.

Скрипт приложений

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

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

  • Отправляйте текстовые сообщения в режиме реального времени, отвечая на действия пользователя.
  • Отправьте текстовое сообщение, вызвав асинхронный вызов 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 .

Отправьте текстовое сообщение с аутентификацией приложения

Вот как отправить текстовое сообщение с аутентификацией приложения :

Питон

  1. В своем рабочем каталоге создайте файл с chat_create_text_message_app.py .
  2. Включите следующий код в 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)
    
  3. В коде замените SPACE именем пространства, которое можно получить с помощью метода spaces.list() в Chat API или из URL-адреса пространства.

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

    python3 chat_create_text_message_app.py
    

API чата возвращает экземпляр Message с подробным описанием отправленного сообщения.

Отправьте текстовое сообщение с аутентификацией пользователя

Вот как отправить текстовое сообщение с аутентификацией пользователя :

Питон

  1. В своем рабочем каталоге создайте файл с chat_create_text_message_user.py .
  2. Включите следующий код в 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 membership.
        print(result)
    
    if __name__ == '__main__':
        main()
    
  3. В коде замените SPACE именем пространства, которое можно получить с помощью метода spaces.list() в Chat API или из URL-адреса пространства.

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

    python3 chat_create_text_message_user.py
    

API чата возвращает экземпляр Message с подробным описанием отправленного сообщения.

Отправлять карточные сообщения

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

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


Создавайте и просматривайте карты с помощью Card Builder.

Откройте конструктор карточек

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

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

В этом примере пользователь отправляет сообщение в приложение чата, а приложение чата отвечает, отправляя карточное сообщение, в котором отображается имя пользователя и изображение аватара:

Приложение чата отвечает карточкой с отображаемым именем отправителя и изображением аватара.

Node.js

узел/аватар-приложение/index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Питон

python/аватар-приложение/main.py
from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

Скрипт приложений

приложения-скрипт/аватар-приложение/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Отправка карточного сообщения асинхронно

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

  • При аутентификации через приложение укажите область авторизации chat.bot . Вы не можете отправить карточное сообщение с аутентификацией пользователя.
  • Вызовите метод create для ресурса Message .

Ниже приведен пример сообщения карты:

Сообщение-карточка, отправленное с помощью Chat API.

Вот как отправить карточное сообщение с аутентификацией приложения:

Питон

  1. В своем рабочем каталоге создайте файл с chat_create_card_message.py .
  2. Включите следующий код в 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)
    
  3. В коде замените SPACE именем пространства, которое можно получить с помощью метода spaces.list в Chat API или из URL-адреса пространства.

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

    python3 chat_create_card_message.py
    

Начать ветку сообщений или ответить на нее

Чтобы запустить цепочку сообщений, отправьте сообщение и оставьте thread.name пустым; Google Chat заполняет его при создании темы. При необходимости, чтобы настроить имя потока, укажите поле thread.threadKey .

Чтобы ответить в поток сообщений, отправьте сообщение, в котором указано поле threadKey или name потока. Если цепочка была создана человеком или другим приложением чата, необходимо использовать поле thread.name .

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

Если установлен messageReplyOption , необходимо также установить thread.name или thread.threadKey .

Вот как запустить поток или ответить на него, используя поле threadKey , определенное как nameOfThread :

Питон

  1. В своем рабочем каталоге создайте файл с chat_create_message_thread.py .
  2. Включите следующий код в 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)
    
  3. В коде замените SPACE именем пространства, которое можно получить с помощью метода spaces.list в Chat API или из URL-адреса пространства.

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

    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 символов и только строчные буквы, цифры и дефисы.
  • Уникальна в пространстве. Приложение чата не может использовать один и тот же собственный идентификатор для разных сообщений.

Вот как отправить сообщение с собственным идентификатором:

Питон

  1. В своем рабочем каталоге создайте файл с chat_create_named_message.py .
  2. Включите следующий код в 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)
    
  3. В коде замените следующее:

    • SPACE : идентификатор пространства, в котором вы хотите опубликовать сообщение, который вы можете получить с помощью метода spaces.list в Chat API или из URL-адреса пространства.
    • NAME : произвольное имя сообщения.
  4. В своем рабочем каталоге соберите и запустите пример:

    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» .