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

В этом руководстве рассказывается, как использовать метод create() для ресурса Message Google Chat API, чтобы:

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

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

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

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

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

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

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

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

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

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

Чтобы узнать больше о функциях обмена сообщениями, доступных для Chat API, ознакомьтесь с обзором сообщений Google Chat.

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

Требования

Node.js

Python

Java

Apps Script

Отправка сообщения от имени приложения Chat

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

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

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

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

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

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

Node.js

chat/client-libraries/cloud/create-message-app-cred.js
import {createClientWithAppCredentials} from './authentication-utils.js';

// This sample shows how to create message with app credential
async function main() {
  // Create a client
  const chatClient = createClientWithAppCredentials();

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      text:
        '👋🌎 Hello world! I created this message by calling ' +
        "the Chat API's `messages.create()` method.",
      cardsV2: [
        {
          card: {
            header: {
              title: 'About this message',
              imageUrl:
                'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg',
            },
            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.',
                    },
                  },
                ],
              },
            ],
          },
        },
      ],
      accessoryWidgets: [
        {
          buttonList: {
            buttons: [
              {
                text: 'View documentation',
                icon: {materialIcon: {name: 'link'}},
                onClick: {
                  openLink: {
                    url: 'https://developers.google.com/workspace/chat/create-messages',
                  },
                },
              },
            ],
          },
        },
      ],
    },
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

await main();

Python

chat/client-libraries/cloud/create_message_app_cred.py
from authentication_utils import create_client_with_app_credentials
from google.apps import chat_v1 as google_chat

# This sample shows how to create message with app credential
def create_message_with_app_cred():
    # Create a client
    client = create_client_with_app_credentials()

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "text": '👋🌎 Hello world! I created this message by calling ' +
                    'the Chat API\'s `messages.create()` method.',
            "cards_v2" : [{ "card": {
                "header": {
                    "title": 'About this message',
                    "image_url": 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
                },
                "sections": [{
                    "header": "Contents",
                    "widgets": [{ "text_paragraph": {
                            "text": '🔡 <b>Text</b> which can include ' +
                                    'hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.'
                        }}, { "text_paragraph": {
                            "text": '🖼️ A <b>card</b> to display visual elements' +
                                    'and request information such as text 🔤, ' +
                                    'dates and times 📅, and selections ☑️.'
                        }}, { "text_paragraph": {
                            "text": '👉🔘 An <b>accessory widget</b> which adds ' +
                                    'a button to the bottom of a message.'
                        }}
                    ]}, {
                        "header": "What's next",
                        "collapsible": True,
                        "widgets": [{ "text_paragraph": {
                                "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>."
                            }}, { "text_paragraph": {
                                "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."
                            }
                        }]
                    }
                ]
            }}],
            "accessory_widgets": [{ "button_list": { "buttons": [{
                "text": 'View documentation',
                "icon": { "material_icon": { "name": 'link' }},
                "on_click": { "open_link": {
                    "url": 'https://developers.google.com/workspace/chat/create-messages'
                }}
            }]}}]
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_app_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageAppCred.java
import com.google.apps.card.v1.Button;
import com.google.apps.card.v1.ButtonList;
import com.google.apps.card.v1.Card;
import com.google.apps.card.v1.Icon;
import com.google.apps.card.v1.MaterialIcon;
import com.google.apps.card.v1.OnClick;
import com.google.apps.card.v1.OpenLink;
import com.google.apps.card.v1.TextParagraph;
import com.google.apps.card.v1.Widget;
import com.google.apps.card.v1.Card.CardHeader;
import com.google.apps.card.v1.Card.Section;
import com.google.chat.v1.AccessoryWidget;
import com.google.chat.v1.CardWithId;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with app credential.
public class CreateMessageAppCred {

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithAppCredentials()) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 Hello world! I created this message by calling " +
                    "the Chat API\'s `messages.create()` method.")
          .addCardsV2(CardWithId.newBuilder().setCard(Card.newBuilder()
            .setHeader(CardHeader.newBuilder()
              .setTitle("About this message")
              .setImageUrl("https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg"))
            .addSections(Section.newBuilder()
              .setHeader("Contents")
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔡 <b>Text</b> which can include " +
                "hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🖼️ A <b>card</b> to display visual elements " +
                "and request information such as text 🔤, " +
                "dates and times 📅, and selections ☑️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "👉🔘 An <b>accessory widget</b> which adds " +
                "a button to the bottom of a message."))))
            .addSections(Section.newBuilder()
              .setHeader("What's next")
              .setCollapsible(true)
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔄 <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."))))))
          .addAccessoryWidgets(AccessoryWidget.newBuilder()
            .setButtonList(ButtonList.newBuilder()
              .addButtons(Button.newBuilder()
                .setText("View documentation")
                .setIcon(Icon.newBuilder()
                  .setMaterialIcon(MaterialIcon.newBuilder().setName("link")))
                .setOnClick(OnClick.newBuilder()
                  .setOpenLink(OpenLink.newBuilder()
                    .setUrl("https://developers.google.com/workspace/chat/create-messages")))))));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

/chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with app credential
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.bot'
 * used by service accounts.
 */
function createMessageAppCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = "spaces/SPACE_NAME";
  const message = {
    text:
      "👋🌎 Hello world! I created this message by calling " +
      "the Chat API's `messages.create()` method.",
    cardsV2: [
      {
        card: {
          header: {
            title: "About this message",
            imageUrl:
              "https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg",
          },
          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.",
                  },
                },
              ],
            },
          ],
        },
      },
    ],
    accessoryWidgets: [
      {
        buttonList: {
          buttons: [
            {
              text: "View documentation",
              icon: { materialIcon: { name: "link" } },
              onClick: {
                openLink: {
                  url: "https://developers.google.com/workspace/chat/create-messages",
                },
              },
            },
          ],
        },
      },
    ],
  };
  const parameters = {};

  // Make the request
  const response = Chat.Spaces.Messages.create(
    message,
    parent,
    parameters,
    getHeaderWithAppCredentials(),
  );

  // Handle the response
  console.log(response);
}

Чтобы запустить этот пример, замените SPACE_NAME идентификатором из поля name чат-группы. Идентификатор можно получить, вызвав метод ListSpaces(), или из URL чат-группы.

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

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

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

Чтобы отправить личное сообщение с помощью 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 отправляет сообщение, оно может использовать один из следующих вариантов уведомления пользователей:

  • Принудительная отправка уведомления. Chat всегда отправляет получателям push-уведомление независимо от их настроек уведомлений или статуса "Не беспокоить". В Chat сообщение выделяется жирным шрифтом и перемещается вверх в списке получателей или на главном экране, а также помечается значком.
  • Отправить беззвучное сообщение. Chat не будет отправлять получателям push-уведомления. В Chat сообщение не выделяется полужирным шрифтом и не перемещается вверх в списке участников или на главном экране, а также не помечается значком. Если сообщение без уведомления является последним в чате, его содержимое не показывается во фрагменте на главном экране.

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

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

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

  • Внешние пользователи. Принудительные уведомления и сообщения без уведомлений не применяются к внешним пользователям (гостям) в чат-группе. Внешние пользователи получают уведомления в соответствии со своими настройками.
  • Упоминания. В тихих сообщениях нельзя упоминать пользователей. Если вы добавите упоминание в сообщение без уведомления, оно будет обработано как обычный текст.
  • Цепочки. Вы не можете начать цепочку или ответить в ней, используя беззвучное сообщение.
  • Тип чат-группы. Принудительные уведомления и сообщения без уведомлений не поддерживаются в прямых переписках и чат-группах, принадлежащих пользователям без аккаунта Google Workspace.
  • Уведомления по электронной почте. При получении сообщений без звука уведомления по электронной почте не отправляются. Сообщения с принудительным уведомлением вызывают уведомления по электронной почте, только если они также содержат упоминание конкретного пользователя.

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

Значение Поведение
NOTIFICATION_TYPE_FORCE_NOTIFY Принудительно отправляет уведомление.
NOTIFICATION_TYPE_SILENT Отправляет сообщение без звука.

Ниже приведен пример тела запроса в формате JSON для отправки сообщения с принудительным уведомлением.

{
  "text": "Critical update: the server is down!",
  "createMessageNotificationOptions": {
    "notificationType": "NOTIFICATION_TYPE_FORCE_NOTIFY"
  }
}

Уведомления для отправителей

Когда приложение Chat отправляет сообщение, оно не уведомляет отправителя автоматически, но помечает сообщение как прочитанное для него.

Чтобы уведомить отправителя о письмах, отправленных от его имени, и оставить письмо непрочитанным, включите в запрос поле createMessageNotificationOptions и задайте для notificationType значение NOTIFICATION_TYPE_INCLUDE_HUMAN_CREATOR.

Отправитель может получить уведомление по электронной почте или push-уведомление в зависимости от своих настроек уведомлений. Включение этого параметра не переопределит настройки уведомлений отправителя для чат-группы. Если отправитель отключил уведомления для чат-группы, он не будет получать их, даже если этот параметр включен.

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

В примере ниже показано тело JSON запроса на отправку сообщения с уведомлением отправителя.

{
  "text": "Alert: Unexpected service interruption",
  "createMessageNotificationOptions": {
    "notificationType": "NOTIFICATION_TYPE_INCLUDE_HUMAN_CREATOR"
  }
}

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

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

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

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

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

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

В следующем примере кода показано, как приложение Chat может отправить текстовое сообщение в чат-группу от имени аутентифицированного пользователя:

Node.js

chat/client-libraries/cloud/create-message-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = [
  'https://www.googleapis.com/auth/chat.messages.create',
];

// This sample shows how to create message with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      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>.',
    },
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

await main();

Python

chat/client-libraries/cloud/create_message_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

def create_message_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "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>.'
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with user credential.
public class CreateMessageUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 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>."));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

/chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = "spaces/SPACE_NAME";
  const message = {
    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>.",
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent);

  // Handle the response
  console.log(response);
}

Чтобы запустить этот пример, замените SPACE_NAME идентификатором из поля name чат-группы. Идентификатор можно получить, вызвав метод ListSpaces(), или из URL чат-группы.

Как начать цепочку или ответить в ней

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

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

  • В теле запроса укажите поле thread.threadKey.
  • Укажите параметр запроса messageReplyOption, чтобы определить, что произойдет, если ключ уже существует.

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

  • В теле запроса укажите поле thread. Если вы задали это значение, то можете указать созданный вами threadKey. В противном случае необходимо использовать name цепочки.
  • Укажите параметр запроса messageReplyOption.

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

Node.js

chat/client-libraries/cloud/create-message-user-cred-thread-key.js
import {protos} from '@google-apps/chat';
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = [
  'https://www.googleapis.com/auth/chat.messages.create',
];

// This sample shows how to create message with user credential with thread key
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Creates the message as a reply to the thread specified by thread_key
    // If it fails, the message starts a new thread instead
    messageReplyOption:
      protos.google.chat.v1.CreateMessageRequest.MessageReplyOption
        .REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
    message: {
      text: 'Hello with user credential!',
      thread: {
        // Thread key specifies a thread and is unique to the chat app
        // that sets it
        threadKey: 'THREAD_KEY',
      },
    },
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

await main();

Python

chat/client-libraries/cloud/create_message_user_cred_thread_key.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

import google.apps.chat_v1.CreateMessageRequest.MessageReplyOption

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with thread key
def create_message_with_user_cred_thread_key():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Creates the message as a reply to the thread specified by thread_key.
        # If it fails, the message starts a new thread instead.
        message_reply_option = MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
        message = {
            "text": "Hello with user credential!",
            "thread": {
                # Thread key specifies a thread and is unique to the chat app
                # that sets it.
                "thread_key": "THREAD_KEY"
            }
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_thread_key()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredThreadKey.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.CreateMessageRequest.MessageReplyOption;
import com.google.chat.v1.Message;
import com.google.chat.v1.Thread;

// This sample shows how to create message with a thread key with user
// credential.
public class CreateMessageUserCredThreadKey {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        // Creates the message as a reply to the thread specified by thread_key.
        // If it fails, the message starts a new thread instead.
        .setMessageReplyOption(
          MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD)
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!")
          // Thread key specifies a thread and is unique to the chat app
          // that sets it.
          .setThread(Thread.newBuilder().setThreadKey("THREAD_KEY")));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

/chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with thread key
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredThreadKey() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = "spaces/SPACE_NAME";
  // Creates the message as a reply to the thread specified by thread_key
  // If it fails, the message starts a new thread instead
  const messageReplyOption = "REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD";
  const message = {
    text: "Hello with user credential!",
    thread: {
      // Thread key specifies a thread and is unique to the chat app
      // that sets it
      threadKey: "THREAD_KEY",
    },
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageReplyOption: messageReplyOption,
  });

  // Handle the response
  console.log(response);
}

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

  • THREAD_KEY: ключ существующей цепочки в чат-группе или уникальное название для новой цепочки.
  • SPACE_NAME – идентификатор из поля name чат-группы. Идентификатор можно получить, вызвав метод ListSpaces(), или из URL чат-группы.

Как указать название сообщения

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

Например, чтобы получить сообщение с помощью метода get(), вы указываете название ресурса, чтобы определить, какое сообщение нужно получить. Название ресурса имеет формат spaces/{space}/messages/{message}, где {message} – это назначенный системой идентификатор или специальное название, которое вы задали при создании сообщения.

Чтобы присвоить сообщению название, укажите пользовательский идентификатор в поле messageId при создании сообщения. Поле messageId задает значение для поля clientAssignedMessageId ресурса Message.

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

  • Начинается с client-. Например, client-custom-name – это допустимый пользовательский идентификатор, а custom-name – нет.
  • Содержит до 63 символов и только строчные буквы, цифры и дефисы.
  • Уникально в пределах чат-группы. Приложение Chat не может использовать один и тот же пользовательский идентификатор для разных сообщений.

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

Node.js

chat/client-libraries/cloud/create-message-user-cred-message-id.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = [
  'https://www.googleapis.com/auth/chat.messages.create',
];

// This sample shows how to create a message with user credentials and a custom
// message id
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Message id lets chat apps get, update or delete a message without needing
    // to store the system assigned ID in the message's resource name
    messageId: 'client-MESSAGE-ID',
    message: {text: 'Hello with user credential!'},
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

await main();

Python

chat/client-libraries/cloud/create_message_user_cred_message_id.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]

# This sample shows how to create message with user credential with message id
def create_message_with_user_cred_message_id():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Message id let chat apps get, update or delete a message without needing
        # to store the system assigned ID in the message's resource name.
        message_id = "client-MESSAGE-ID",
        message = {
            "text": "Hello with user credential!"
        }
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_with_user_cred_message_id()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredMessageId.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with message id specified with user
// credential.
public class CreateMessageUserCredMessageId {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!"))
        // Message ID lets chat apps get, update or delete a message without
        // needing to store the system assigned ID in the message's resource
        // name.
        .setMessageId("client-MESSAGE-ID");
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

/chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with message id
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredMessageId() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = "spaces/SPACE_NAME";
  // Message id lets chat apps get, update or delete a message without needing
  // to store the system assigned ID in the message's resource name
  const messageId = "client-MESSAGE-ID";
  const message = { text: "Hello with user credential!" };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent, {
    messageId: messageId,
  });

  // Handle the response
  console.log(response);
}

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

  • SPACE_NAME – идентификатор из поля name чат-группы. Идентификатор можно получить, вызвав метод ListSpaces(), или из URL чат-группы.
  • MESSAGE-ID – название сообщения, которое начинается с custom-. Оно должно отличаться от названий других сообщений, созданных приложением Chat в указанной чат-группе.

Как процитировать сообщение

Вы можете процитировать другое сообщение, вызвав CreateMessage() (rpc, rest) и задав quotedMessageMetadata (rpc, rest) в запросе.

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

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

Node.js

import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create a message that quotes another message.
async function main() {

  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {

    // TODO(developer): Replace SPACE_NAME .
    parent: 'spaces/SPACE_NAME',

    message: {
      text: 'I am responding to a quoted message!',

      // quotedMessageMetadata lets Chat apps respond to a message by quoting it.
      quotedMessageMetadata: {

        // TODO(developer): Replace QUOTED_MESSAGE_NAME
        // and QUOTED_MESSAGE_LAST_UPDATE_TIME.
        name: 'QUOTED_MESSAGE_NAME',
        lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME'
      }
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat
from google.protobuf.timestamp_pb2 import Timestamp

SCOPES = ['https://www.googleapis.com/auth/chat.messages.create']

# This sample shows how to create a message that quotes another message.
def create_message_quote_message():
    '''Creates a message that quotes another message.'''

    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Create a timestamp from the RFC-3339 string.
    # TODO(developer): Replace QUOTED_MESSAGE_LAST_UPDATE_TIME.
    last_update_time = Timestamp()
    last_update_time.FromJsonString('QUOTED_MESSAGE_LAST_UPDATE_TIME')

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(

        # TODO(developer): Replace SPACE_NAME.
        parent='spaces/SPACE_NAME',

        # Create the message.
        message = google_chat.Message(
            text='I am responding to a quoted message!',

            # quotedMessageMetadata lets Chat apps respond to a message by quoting it.
            quoted_message_metadata=google_chat.QuotedMessageMetadata(

                name='QUOTED_MESSAGE_NAME',
                last_update_time=last_update_time
            )
        )
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_quote_message()

Java

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;
import com.google.chat.v1.QuotedMessageMetadata;
import com.google.protobuf.util.Timestamps;
import com.google.workspace.api.chat.samples.utils.AuthenticationUtils;
import java.text.ParseException;

// This sample shows how to create a message that quotes another message.
public class CreateMessageQuoteMessage {
  public static void main(String[] args) throws Exception, ParseException {
    // Create a client.
    ChatServiceClient chatClient = AuthenticationUtils.createClientWithUserCredentials();

    // Initialize request argument(s).
    // TODO(developer): Replace SPACE_NAME, QUOTED_MESSAGE_NAME,
    // and QUOTED_MESSAGE_LAST_UPDATE_TIME here.
    String parent = "spaces/SPACE_NAME";
    String quotedMessageName = "QUOTED_MESSAGE_NAME";
    String lastUpdateTime = "QUOTED_MESSAGE_LAST_UPDATE_TIME";

    QuotedMessageMetadata quotedMessageMetadata =
        QuotedMessageMetadata.newBuilder()
            .setName(quotedMessageName)
            .setLastUpdateTime(Timestamps.parse(lastUpdateTime))
            .build();

    Message message = Message.newBuilder()
        .setText("I am responding to a quoted message!")
        .setQuotedMessageMetadata(quotedMessageMetadata)
        .build();

    CreateMessageRequest request =
        CreateMessageRequest.newBuilder()
            .setParent(parent)
            .setMessage(message)
            .build();

    // Make the request.
    Message response = chatClient.createMessage(request);

    // Handle the response.
    System.out.println(response);
  }
}

Apps Script

/**
 * Creates a message that quotes another message.
 *
 * Relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageQuoteMessage() {

  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';

  const message = {

    // The text content of the message.
    text: 'I am responding to a quoted message!',

    // quotedMessageMetadata lets Chat apps respond to a message by quoting it.
    //
    // TODO(developer): Replace QUOTED_MESSAGE_NAME
    // and QUOTED_MESSAGE_LAST_UPDATE_TIME .
    quotedMessageMetadata: {
      name: 'QUOTED_MESSAGE_NAME',
      lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME',
    }
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent);

  // Handle the response
  console.log(response);
}

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

  • SPACE_NAME – идентификатор из поля name чат-группы. Идентификатор можно получить, вызвав метод ListSpaces() (rpc, rest) или из URL чат-группы.
  • QUOTED_MESSAGE_NAME – ресурс сообщения name (rpc, rest) сообщения, которое нужно процитировать, в формате spaces/{space}/messages/{message}.
  • QUOTED_MESSAGE_LAST_UPDATE_TIME – время последнего обновления сообщения, которое вы хотите процитировать. Если сообщение не редактировалось, соответствует createTime (rpc, rest). Если сообщение редактировалось, соответствует lastUpdateTime (rpc, rest).

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

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

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