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

В этом руководстве описаны различные способы отправки сообщений приложениями 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

Питон

  • Python 3.6 или выше
  • Инструмент управления пакетами pip

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

    pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client

  • Опубликованное приложение чата. Чтобы создать и опубликовать приложение 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 httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

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

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

Приложения чата могут создавать карточные сообщения в ответ на взаимодействие с пользователем, например, когда пользователь отправляет приложению чата сообщение или добавляет приложение чата в пространство. Дополнительные сведения о реагировании на взаимодействия с пользователем см. в разделе Получение событий взаимодействия с приложением 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 httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

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

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

Питон

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

  2. Включите следующий код в chat_create_message_thread.py :

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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 сообщения из тела ответа , возвращаемого при отправке сообщения.

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

К пользовательским именам предъявляются следующие требования:

  • Начните с client- . Например, client-custom-name является допустимым пользовательским именем, а custom-name нет.
  • Содержит только строчные буквы, цифры и дефисы.
  • Длина не должна превышать 63 символов.
  • Указание использованного пользовательского имени при отправке сообщения возвращает ошибку, но другие методы, такие как update и delete работают должным образом.

Вот как отправить сообщение и назвать его:

Питон

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

  2. Включите следующий код в chat_create_named_message.py :

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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-custom-name',

    # The message to create.
    body={'text': 'Hello, world!'}

).execute()

print(result)

  3. В коде замените SPACE именем пространства, которое можно получить с помощью метода spaces.list в Chat API или из URL-адреса пространства.

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

    python3 chat_create_named_message.py

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

Устранение неполадок

Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.

Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Информацию о просмотре, отладке и исправлении ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .