Wysyłanie wiadomości przy użyciu interfejsu Google Chat API

Z tego przewodnika dowiesz się, jak używać metody create() w zasobie Message interfejsu Google Chat API, aby:

  • wysyłać wiadomości zawierające tekst, karty i interaktywne widżety;
  • wysyłać prywatne wiadomości do konkretnego użytkownika Google Chat;
  • rozpocząć wątek wiadomości lub odpowiedzieć na niego;
  • Nazwij wiadomość, aby można było ją określić w innych żądaniach do interfejsu Chat API.

Maksymalny rozmiar wiadomości (wraz z tekstem i kartami) to 32 000 bajtów. Aby wysłać wiadomość, która przekracza ten rozmiar, aplikacja do Google Chat musi wysłać kilka wiadomości.

Oprócz wywoływania interfejsu Chat API w celu tworzenia wiadomości aplikacje do Google Chat mogą tworzyć i wysyłać wiadomości w odpowiedzi na interakcje użytkowników, np. publikować wiadomość powitalną po dodaniu aplikacji do Google Chat do pokoju przez użytkownika. Odpowiadając na interakcje, aplikacje do Google Chat mogą korzystać z innych typów funkcji do obsługi wiadomości, w tym interaktywnych okien dialogowych i interfejsów podglądu linków. Aby odpowiedzieć użytkownikowi, aplikacja do Google Chat zwraca wiadomość synchronicznie, bez wywoływania interfejsu Chat API. Informacje o wysyłaniu wiadomości w odpowiedzi na interakcje znajdziesz w artykule Odbieranie interakcji z aplikacją Google Chat i odpowiadanie na nie.

Jak Google Chat wyświetla wiadomości utworzone za pomocą interfejsu Chat API i jak przypisuje ich autorstwo

Metodę create() możesz wywołać za pomocą uwierzytelniania aplikacji i uwierzytelniania użytkownika. Chat przypisuje nadawcę wiadomości w różny sposób w zależności od typu używanego uwierzytelniania.

Gdy uwierzytelniasz się jako aplikacja Google Chat, aplikacja Google Chat wysyła wiadomość.

wywołanie metody create() z uwierzytelnianiem aplikacji,
Rysunek 1. W przypadku uwierzytelniania aplikacji wiadomość wysyła aplikacja Google Chat. Aby zaznaczyć, że nadawca nie jest osobą, Chat wyświetla obok jego nazwy ikonę App.

Gdy uwierzytelniasz się jako użytkownik, aplikacja Google Chat wysyła wiadomość w imieniu użytkownika. Google Chat przypisuje też aplikację do Google Chat do wiadomości, wyświetlając jej nazwę.

wywołanie metody create() z uwierzytelnianiem użytkownika,
Rysunek 2. W przypadku uwierzytelniania użytkownika użytkownik wysyła wiadomość, a Google Chat wyświetla nazwę aplikacji do Google Chat obok nazwy użytkownika.

Typ uwierzytelniania określa też, które funkcje i interfejsy wiadomości możesz uwzględnić w wiadomości. Dzięki uwierzytelnianiu aplikacji aplikacje do Google Chat mogą wysyłać wiadomości zawierające tekst sformatowany, interfejsy oparte na kartach i interaktywne widżety. Dzięki uwierzytelnianiu użytkowników możesz wysyłać wiadomości tekstowe lub tworzyć wiadomości z kartami, jak opisano w artykule Tworzenie i aktualizowanie kart interaktywnych.

Więcej informacji o funkcjach przesyłania wiadomości dostępnych w interfejsie Chat API znajdziesz w omówieniu wiadomości na czacie w Google Chat.

Z tego przewodnika dowiesz się, jak używać obu typów uwierzytelniania do wysyłania wiadomości za pomocą interfejsu Chat API.

Wymagania wstępne

Node.js

Python

Java

Google Apps Script

Wysyłanie wiadomości jako aplikacja do Google Chat

W tej sekcji dowiesz się, jak wysyłać wiadomości zawierające tekst, karty i interaktywne widżety dodatkowe za pomocą uwierzytelniania aplikacji.

Wiadomość wysłana z uwierzytelnianiem aplikacji
Rysunek 4. Aplikacja Google Chat wysyła wiadomość z tekstem, kartą i przyciskiem dodatkowym.

Aby wywołać metodę CreateMessage() przy użyciu uwierzytelniania aplikacji, musisz podać w żądaniu te pola:

  • chat.bot Zakres autoryzacji.
  • Zasób Space, w którym chcesz opublikować wiadomość. Aplikacja Google Chat musi być członkiem pokoju.
  • Zasób Message, który ma zostać utworzony. Aby określić treść wiadomości, możesz dodać tekst sformatowany (text), co najmniej 1 interfejs karty (cardsV2) lub oba te elementy.

Opcjonalnie możesz też podać te informacje:

Poniższy kod pokazuje, jak aplikacja do Google Chat może wysłać wiadomość opublikowaną jako aplikacja do Google Chat, która zawiera tekst, kartę i klikalny przycisk na dole wiadomości:

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));
    }
  }
}

Google 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);
}

Aby uruchomić ten przykład, zastąp SPACE_NAME identyfikatorem z pola name pokoju. Identyfikator możesz uzyskać, wywołując metodę ListSpaces(), lub z adresu URL pokoju.

Dodawanie interaktywnych widżetów u dołu wiadomości

W pierwszym przykładowym kodzie w tym przewodniku wiadomość aplikacji Google Chat wyświetla u dołu klikalny przycisk, który jest nazywany widżetem dodatkowym. Widżety dodatkowe pojawiają się po tekście lub kartach w wiadomości. Możesz używać tych widżetów, aby zachęcać użytkowników do interakcji z wiadomością na wiele sposobów, m.in.:

  • ocenić dokładność wiadomości lub zadowolenie z niej,
  • Zgłoś problem z wiadomością lub aplikacją do Google Chat.
  • otworzyć link do powiązanych treści, np. dokumentacji;
  • odrzucać lub odkładać podobne wiadomości z aplikacji Google Chat na określony czas;

Aby dodać widżety akcesoriów, w treści żądania uwzględnij pole accessoryWidgets[] i określ co najmniej 1 widżet, który chcesz dodać.

Na obrazie poniżej widać aplikację do Google Chat, która dołącza do wiadomości tekstowej widżety dodatkowe, aby użytkownicy mogli ocenić swoje wrażenia z korzystania z aplikacji.

Widżet akcesoriów.
Ilustracja 5. Wiadomość z aplikacji Google Chat z tekstem i widżetami dodatkowymi

Poniżej znajduje się treść żądania, które tworzy SMS-a z 2 przyciskami dodatkowymi. Gdy użytkownik kliknie przycisk, odpowiednia funkcja (np. doUpvote) przetwarza interakcję:

{
  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"
    }}
  }]}}]
}

Wysyłanie wiadomości prywatnej

Aplikacje do Google Chat mogą wysyłać wiadomości prywatnie, dzięki czemu są one widoczne tylko dla określonego użytkownika w pokoju. Gdy aplikacja do Google Chat wysyła wiadomość prywatną, wyświetla się etykieta informująca użytkownika, że wiadomość jest widoczna tylko dla niego.

Aby wysłać wiadomość prywatnie za pomocą interfejsu Chat API, w treści żądania określ pole privateMessageViewer. Aby określić użytkownika, ustaw wartość na zasób User, który reprezentuje użytkownika Google Chat. Możesz też użyć pola name zasobu User, jak w tym przykładzie:

{
  text: "Hello private world!",
  privateMessageViewer: {
    name: "users/USER_ID"
  }
}

Aby użyć tego przykładu, zastąp USER_ID unikalnym identyfikatorem użytkownika, takim jak 12345678987654321 lub hao@cymbalgroup.com. Więcej informacji o określaniu użytkowników znajdziesz w artykule Identyfikowanie i określanie użytkowników Google Chat.

Aby wysłać wiadomość prywatnie, musisz pominąć w żądaniu te elementy:

Wysyłaj powiadomienia wymuszone lub wiadomości bez powiadomienia

Gdy aplikacja do Google Chat wysyła wiadomość, może użyć jednej z tych opcji, aby powiadomić użytkowników:

  • Wymuś powiadomienie: Google Chat zawsze wysyła powiadomienie push do odbiorców, niezależnie od ich ustawień powiadomień lub stanu Nie przeszkadzać. W Google Chat wiadomość powoduje pogrubienie i przesunięcie na liście kontaktów lub na liście głównej odbiorców oraz wyświetlenie plakietki.
  • Wysyłanie cichej wiadomości: Google Chat blokuje powiadomienia push dla odbiorców. W Google Chat wiadomość nie powoduje pogrubienia ani przesunięcia na liście odbiorców lub na liście na stronie głównej i nie wyświetla się z plakietką. Jeśli cicha wiadomość jest ostatnią wiadomością w rozmowie, jej treść nie jest wyświetlana we fragmencie na stronie głównej.

Niezależnie od tego, czy są wymuszone czy ciche, te wiadomości zawierają wskaźnik wizualny, który informuje odbiorców o specjalnym zachowaniu powiadomienia.

Powiadomienia wymuszone i ciche wiadomości są dostępne tylko w przypadku aplikacji do Google Chat korzystających z uwierzytelniania aplikacji.

Wymuszone powiadomienia i ciche wiadomości mają te ograniczenia:

  • Użytkownicy zewnętrzni: powiadomienia wymuszone i wiadomości bez powiadomienia nie mają zastosowania do użytkowników zewnętrznych (gości) w pokoju. Użytkownicy spoza organizacji otrzymują powiadomienia zgodnie z własnymi ustawieniami.
  • Wzmianki: wiadomości ciche nie obsługują wzmianek o użytkownikach. Jeśli dodasz wzmiankę w cichej wiadomości, zostanie ona potraktowana jako zwykły tekst.
  • Wątki: nie możesz rozpocząć wątku ani odpowiedzieć na niego za pomocą cichej wiadomości.
  • Typ pokoju: powiadomienia wymuszone i wiadomości bez powiadomienia nie są obsługiwane w czatach prywatnych ani pokojach należących do osób, które nie mają konta Google Workspace.
  • E-maile z powiadomieniami: wiadomości bez dźwięku nie powodują wysyłania e-maili z powiadomieniami. Wiadomości z wymuszonym powiadomieniem powodują wysłanie powiadomienia e-mail tylko wtedy, gdy zawierają też wzmiankę o konkretnym użytkowniku.

Aby wymusić powiadomienie lub wysłać cichą wiadomość, dodaj do żądania pole createMessageNotificationOptions i ustaw notificationType na jedną z tych wartości:

Wartość Zachowanie
NOTIFICATION_TYPE_FORCE_NOTIFY Wymusza powiadomienie.
NOTIFICATION_TYPE_SILENT Wysyła wiadomość dyskretnie.

Ten przykład pokazuje treść JSON żądania wysłania wiadomości z wymuszonym powiadomieniem:

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

Wysyłanie SMS-a w imieniu użytkownika

W tej sekcji dowiesz się, jak wysyłać wiadomości w imieniu użytkownika za pomocą uwierzytelniania użytkownika. Dzięki uwierzytelnianiu użytkowników możesz wysyłać wiadomości tekstowe lub tworzyć wiadomości z kartami w imieniu użytkownika. Szczegółowe informacje o wysyłaniu kart w imieniu użytkownika znajdziesz w artykule Tworzenie i aktualizowanie kart interaktywnych.

Wiadomość wysłana z uwierzytelnianiem użytkownika
Rysunek 3. Aplikacja do Google Chat wysyła wiadomość tekstową w imieniu użytkownika.

Aby wywołać metodę CreateMessage() przy użyciu uwierzytelniania użytkownika, musisz podać w żądaniu te pola:

  • Zakres autoryzacji, który obsługuje uwierzytelnianie użytkownika w przypadku tej metody. W tym przykładzie użyto zakresu chat.messages.create.
  • Zasób Space, w którym chcesz opublikować wiadomość. Uwierzytelniony użytkownik musi być członkiem pokoju.
  • Zasób Message, który ma zostać utworzony. Aby określić treść wiadomości, musisz użyć pola text.

Opcjonalnie możesz też podać te informacje:

Poniższy kod pokazuje przykład, jak aplikacja Google Chat może wysłać wiadomość tekstową w danym pokoju w imieniu uwierzytelnionego użytkownika:

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));
    }
  }
}

Google 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);
}

Aby uruchomić ten przykład, zastąp SPACE_NAME identyfikatorem z pola name pokoju. Identyfikator możesz uzyskać, wywołując metodę ListSpaces(), lub z adresu URL pokoju.

Rozpoczynanie wątku lub odpowiadanie w nim

W przypadku pokoi, które używają wątków, możesz określić, czy nowa wiadomość ma rozpoczynać wątek, czy ma być odpowiedzią w istniejącym wątku.

Domyślnie wiadomości tworzone za pomocą interfejsu Chat API rozpoczynają nowy wątek. Aby ułatwić sobie identyfikację wątku i odpowiedź na niego później, możesz określić w żądaniu klucz wątku:

Aby utworzyć wiadomość, która odpowiada na istniejący wątek:

  • W treści żądania uwzględnij pole thread. Jeśli jest ustawiona, możesz określić utworzoną przez siebie zmienną threadKey. W przeciwnym razie musisz użyć name wątku.
  • Określ parametr zapytania messageReplyOption.

Poniższy kod pokazuje, jak aplikacja Google Chat może wysłać wiadomość tekstową, która rozpoczyna dany wątek lub odpowiada na niego, zidentyfikowany przez klucz danego pokoju, w imieniu uwierzytelnionego użytkownika:

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));
    }
  }
}

Google 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);
}

Aby uruchomić ten przykład, zastąp te elementy:

  • THREAD_KEY: klucz istniejącego wątku w pokoju lub unikalna nazwa nowego wątku.
  • SPACE_NAME: identyfikator z pola name pokoju. Identyfikator możesz uzyskać, wywołując metodę ListSpaces(), lub z adresu URL pokoju.

Nadawanie nazwy wiadomości

Aby pobrać lub określić wiadomość w przyszłych wywołaniach interfejsu API, możesz nadać jej nazwę, ustawiając pole messageId w żądaniu. Nazwanie wiadomości pozwala określić wiadomość bez konieczności przechowywania przypisanego przez system identyfikatora z nazwy zasobu wiadomości (reprezentowanej w polu name).

Na przykład, aby pobrać wiadomość za pomocą metody get(), użyj nazwy zasobu, aby określić, którą wiadomość chcesz pobrać. Nazwa zasobu ma format spaces/{space}/messages/{message}, gdzie {message} reprezentuje przypisany przez system identyfikator lub niestandardową nazwę ustawioną podczas tworzenia wiadomości.

Aby nadać nazwę wiadomości, podczas jej tworzenia wpisz identyfikator niestandardowy w polu messageId. Pole messageId ustawia wartość pola clientAssignedMessageId zasobu Message.

Wiadomość możesz nazwać tylko podczas jej tworzenia. Nie możesz nazwać ani zmodyfikować identyfikatora niestandardowego w przypadku istniejących wiadomości. Identyfikator niestandardowy musi spełniać te wymagania:

  • Zaczyna się od client-. Na przykład client-custom-name jest prawidłowym identyfikatorem niestandardowym, ale custom-name już nie.
  • Może zawierać maksymalnie 63 znaki i tylko małe litery, cyfry oraz łączniki.
  • jest unikalny w obrębie pokoju, Aplikacja Google Chat nie może używać tego samego identyfikatora niestandardowego w przypadku różnych wiadomości.

Poniższy kod pokazuje, jak aplikacja do Google Chat może wysłać wiadomość tekstową z identyfikatorem do danego pokoju w imieniu uwierzytelnionego użytkownika:

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));
    }
  }
}

Google 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);
}

Aby uruchomić ten przykład, zastąp te elementy:

  • SPACE_NAME: identyfikator z pola name pokoju. Identyfikator możesz uzyskać, wywołując metodę ListSpaces(), lub z adresu URL pokoju.
  • MESSAGE-ID: nazwa wiadomości, która zaczyna się od custom-. Musi być unikalna i różnić się od nazw innych wiadomości utworzonych przez aplikację Google Chat w określonym pokoju.

Cytowanie wiadomości

Możesz zacytować inną wiadomość, wywołując metodę CreateMessage() (rpc, rest) i ustawiając w żądaniu parametr quotedMessageMetadata (rpc, rest).

Możesz cytować wiadomości w wątku lub na czacie głównym, ale nie możesz cytować wiadomości z innego wątku.

Poniższy kod pokazuje, jak utworzyć wiadomość, która cytuje inną wiadomość:

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);
  }
}

Google 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);
}

Aby uruchomić ten przykład, zastąp te elementy:

  • SPACE_NAME: identyfikator z pola name pokoju. Identyfikator możesz uzyskać, wywołując metodę ListSpaces() (rpc, rest) lub z adresu URL pokoju.
  • QUOTED_MESSAGE_NAME: zasób wiadomości name (rpc, rest) wiadomości do zacytowania w formacie spaces/{space}/messages/{message}.
  • QUOTED_MESSAGE_LAST_UPDATE_TIME: czas ostatniej aktualizacji wiadomości, którą chcesz zacytować. Jeśli wiadomość nigdy nie była edytowana, odpowiada createTime (rpc, rest). Jeśli wiadomość była edytowana, odpowiada lastUpdateTime (rpc, rest).

Rozwiązywanie problemów

Gdy aplikacja Google Chat lub karta zwraca błąd, interfejs Google Chat wyświetla komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć żądania”. Czasami interfejs Google Chat nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta Google Chat generuje nieoczekiwany wynik, np. wiadomość na karcie może się nie pojawić.

Chociaż komunikat o błędzie może nie wyświetlać się w interfejsie Google Chat, opisowe komunikaty o błędach i dane dziennika są dostępne, aby pomóc Ci naprawić błędy, gdy włączone jest rejestrowanie błędów w aplikacjach do Google Chat. Pomoc dotyczącą wyświetlania, debugowania i naprawiania błędów znajdziesz w artykule Rozwiązywanie i naprawianie błędów w Google Chat.