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

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

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

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

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

Как 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"
  }
}

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

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

Сообщение отправлено с аутентификацией пользователя
Рисунок 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…