Na tej stronie opisujemy, jak aplikacja Google Chat może odbierać interakcje użytkowników w Google Chat i na nie odpowiadać.
Aby utworzyć interaktywne interfejsy aplikacji Google Chat, użyj tych komponentów:
- Aktywatory: sposoby, w jakie użytkownicy Google Chat mogą wywołać aplikację Google Chat, np. dodając ją do pokoju lub wysyłając do niej wiadomość.
- Obiekty zdarzeń: dane, które aplikacje Google Chat otrzymują z aktywatorów lub interakcji z interfejsem.
- Działania: sposoby, w jakie aplikacje Google Chat mogą reagować na interakcje, np. wysyłanie wiadomości lub zwracanie interfejsu opartego na kartach.
Aplikacje do Google Chat mogą tworzyć i wyświetlać interfejsy na te sposoby:
- Wiadomości, które mogą zawierać tekst, karty statyczne lub interaktywne oraz przyciski dodatkowe.
- Strony główne (strona główna aplikacji), które pojawiają się na karcie Strona główna w czatach indywidualnych z aplikacją Google Chat.
- Okna, czyli karty, które otwierają się w nowym oknie i zwykle proszą użytkowników o przesłanie informacji.
- Podglądy linków, czyli karty z podglądem informacji o usłudze zewnętrznej.
Wymagania wstępne
- Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz i skonfiguruj Google Chat API.
Jak działają interakcje użytkowników
Gdy użytkownik wchodzi w interakcję z aplikacją Google Chat, Google Chat wywołuje skonfigurowany regułę i wysyła obiekt zdarzenia do punktu końcowego lub funkcji aplikacji Google Chat. Aplikacja do Google Chat przetwarza obiekt zdarzenia i może synchronicznie zwrócić działanie w ciągu 30 sekund lub odpowiedzieć asynchronicznie za pomocą interfejsu Chat API.
Ten diagram pokazuje, jak aplikacje Google Chat przetwarzają interakcje użytkowników i na nie odpowiadają:
Aktywatory
Aktywatory to konkretne sposoby, w jakie użytkownicy wywołują aplikację do Google Chat za pomocą interfejsu Google Chat, np. za pomocą @wzmianek lub poleceń aplikacji.
W tabeli poniżej znajdziesz aktywatory Google Chat, ich opisy i typowe reakcje aplikacji do Google Chat:
| Aktywator | Opis | Typowa odpowiedź |
|---|---|---|
| Dodano do pokoju |
Użytkownik dodaje aplikację Google Chat do pokoju lub administrator Google Workspace instaluje aplikację Google Chat w pokojach czatu dla użytkowników w organizacji. Informacje o aplikacjach do Google Chat zainstalowanych przez administratorów znajdziesz w artykule Instalowanie aplikacji z Marketplace w domenie w dokumentacji pomocy dla administratorów Google Workspace. |
Aplikacja do Google Chat wysyła wiadomość powitalną, która wyjaśnia, co robi aplikacja i jak użytkownicy w pokoju mogą z nią wchodzić w interakcje. |
| Wiadomość |
Użytkownik wchodzi w interakcję z aplikacją Google Chat w wiadomości na jeden z tych sposobów:
|
Aplikacja do Google Chat odpowiada na podstawie treści wiadomości. Na przykład aplikacja do Google Chat odpowiada wiadomością, dołącza kartę podglądu linku lub sugeruje elementy w menu wielokrotnego wyboru. |
| Usunięto z pokoju |
Użytkownik usuwa aplikację Google Chat z pokoju lub administrator Google Workspace odinstalowuje aplikację Google Chat dla użytkownika w organizacji. Użytkownicy nie mogą usuwać aplikacji Google Chat zainstalowanych przez administratora. Jeśli użytkownik zainstalował wcześniej aplikację do Google Chat, pozostanie ona zainstalowana niezależnie od tego, czy administrator Google Workspace spróbuje ją odinstalować. |
Aplikacja Google Chat usuwa wszystkie powiadomienia przychodzące skonfigurowane dla pokoju (np. usuwa webhook) i czyści pamięć wewnętrzną. Aplikacje do Google Chat nie mogą odpowiadać wiadomościami na ten aktywator, ponieważ nie są już członkami pokoju. |
| Polecenie aplikacji |
Użytkownik wywołuje polecenie aplikacji Google Chat (np. polecenie po ukośniku, szybkie polecenie lub działanie na wiadomości). |
Aplikacja do Google Chat odpowie na polecenie. Może na przykład odpowiedzieć wiadomością lub otworzyć okno. |
| Strona główna aplikacji |
Użytkownik otwiera kartę Strona główna w czacie indywidualnym w aplikacji Google Chat lub wchodzi w interakcję z widżetem na karcie strony głównej. |
Aplikacja do obsługi czatu zwraca obiekt RenderActions, który przesyła kartę strony głównej (pushCard) lub aktualizuje wyświetlaną kartę strony głównej (updateCard).
|
Punkty końcowe lub funkcje wywołania zwrotnego dla tych aktywatorów konfigurujesz w konsoli Google Cloud na stronie Konfiguracja interfejsu Chat API. Szczegółowe instrukcje znajdziesz w artykule Konfigurowanie interfejsu Google Chat API.
Konfigurowanie promptów początkowych
Prompty początkowe pomagają użytkownikom odkrywać funkcje aplikacji do Google Chat, gdy otwierają pusty czat indywidualny z aplikacją. Możesz skonfigurować maksymalnie 3 prompty początkowe.
Aby dodać i skonfigurować prompty rozpoczynające:
W konsoli Google Cloud otwórz stronę Konfiguracja interfejsu Chat API:
W sekcji Funkcje interaktywne znajdź Prompty początkowe i kliknij Dodaj domyślny prompt lub polecenie.
W polu Pozycja (1–3) wpisz liczbę od
1do3, aby określić kolejność wyświetlania. Każdy skonfigurowany prompt musi mieć unikalną pozycję.W sekcji Wybór typu określ, jak ma się zachowywać prośba:
- Prompt tekstowy: wypełnia pasek tworzenia wiadomości wstępnie zdefiniowanym tekstem, gdy użytkownik kliknie element z promptem.
- Polecenie: po kliknięciu uruchamia zarejestrowane polecenie po ukośniku lub szybkie polecenie. Działań związanych z wiadomościami nie można mapować na prompty rozpoczynające.
Skonfiguruj prompta na podstawie wybranego typu:
Jeśli wybierzesz Prompt tekstowy:
- W polu Tytuł wpisz tytuł prompta wyświetlany w elemencie (maksymalnie 30 znaków). Tytuł nie może zawierać ukośników ani ukośników lewych.
- W polu Tekst prompta wpisz tekst, który ma się pojawiać na pasku tworzenia wiadomości (maksymalnie 60 znaków). Tekst prompta nie może zawierać ukośników ani ukośników lewych.
- Opcjonalnie: dodaj zlokalizowane tytuły i teksty dla użytkowników posługujących się innymi językami:
- W sekcji Zlokalizowane instrukcje kliknij Dodaj język.
- W sekcji Język wybierz obsługiwany język z menu.
- W polu Zlokalizowany tytuł wpisz zlokalizowany tytuł (maksymalnie 30 znaków).
- W polu Przetłumaczony tekst wpisz przetłumaczony tekst prośby (maksymalnie 60 znaków).
- W razie potrzeby powtórz te czynności, aby dodać więcej języków.
Jeśli wybierzesz Polecenie:
- W polu Identyfikator polecenia wybierz polecenie z menu.
Kliknij Gotowe, a następnie u dołu strony kliknij Zapisz.
Obsługa ponownych prób wywołania HTTP do usługi
Jeśli żądanie HTTPS do Twojej usługi nie powiedzie się (np. z powodu przekroczenia limitu czasu, tymczasowej awarii sieci lub kodu stanu HTTPS innego niż 2xx), Google Chat może spróbować ponownie dostarczyć wiadomość kilka razy w ciągu kilku minut (ale nie jest to gwarantowane). W związku z tym w niektórych sytuacjach aplikacja do Google Chat może otrzymać to samo zdarzenie kilka razy. Jeśli żądanie zostanie zrealizowane, ale zwróci nieprawidłowy ładunek odpowiedzi, Google Chat nie ponowi żądania.
Obiekty zdarzeń
Aplikacje do Google Chat otrzymują obiekty zdarzeń, gdy uruchamiany jest aktywator Google Chat lub gdy użytkownicy Google Chat wchodzą w interakcję z interfejsem aplikacji do Google Chat (np. klikają przycisk lub przesyłają okno). Obiekt zdarzenia umożliwia używanie danych interakcji do reagowania lub aktualizowania interfejsu.
W 2025 r. aplikacje Google Chat zostały rozszerzone o obsługę zdarzeń dodatków, co jest domyślnym ustawieniem w przypadku nowych aplikacji Google Chat od lipca 2025 r. W dokumentacji Google Chat zdarzenia dodatków są standardowym typem zdarzeń wyświetlanym w przewodnikach i przykładowych kodach. Dokumentacja zdarzeń Google Chat (w przypadku aplikacji Google Chat, które nie są dodatkami do Google Workspace) jest podzielona na zwinięte sekcje (np. Aplikacje Google Chat, które nie są dodatkami: odbieranie zdarzeń interakcji i odpowiadanie na nie).
Określanie typów zdarzeń i odpowiedzi
Gdy aplikacja Google Chat otrzyma obiekt zdarzenia, struktura ładunku i sposób odpowiedzi zależą od tego, czy aplikacja Google Chat jest skonfigurowana jako dodatek do Google Workspace.
Aby sprawdzić, jakiego typu obiekty zdarzeń otrzymuje Twoja aplikacja i jak powinna na nie reagować, sprawdź konfigurację aplikacji, korzystając z tej tabeli:
| Typ aplikacji | Odbiera zdarzenia dodatków (domyślne ustawienie dla nowych aplikacji utworzonych po lipcu 2025 r.) |
Odbiera zdarzenia Google Chat (poprzednie ustawienie domyślne, przed lipcem 2025 r.) |
|---|---|---|
| Aplikacje Apps Script Sprawdź plik manifestu ( appsscript.json). |
Obiekt chat jest skonfigurowany w addOns:
|
Obiekt chat jest skonfigurowany w głównym katalogu pliku manifestu:
|
| Inne aplikacje Sprawdź stronę Konfiguracja interfejsu Google Chat API |
Pole wyboru „Utwórz tę aplikację do Google Chat jako dodatek do Google Workspace” jest zaznaczone. | Pole wyboru „Utwórz tę aplikację do Google Chat jako dodatek do Google Workspace” nie jest zaznaczone. |
| Gdzie można znaleźć dokumentację | W przewodnikach i przykładowych kodach Dokumentacja referencyjna zdarzeń: obiekty zdarzeń dodatków |
Zwijane sekcje (np. Aplikacje do Google Chat, które nie są dodatkami: odbieranie zdarzeń interakcji i odpowiadanie na nie) Dokumentacja zdarzeń: Zdarzenia interakcji w interfejsie Chat API |
| Jak odpowiadać | Zwróć działanie, np. DataActions lub RenderActions.Zobacz, jak odpowiedzieć działaniem |
Zwróć zasób Message.Zobacz, jak odpowiedzieć wiadomością |
Ładunki obiektów zdarzeń
Każdy obiekt zdarzenia dodatków zawiera obiekt commonEventObject ze szczegółowymi informacjami o hoście i platformie (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters i formInputs) oraz obiekt chat zawierający kontekst dotyczący Google Chat:
- W przypadku aktywatora Strona główna aplikacji (gdy użytkownik otwiera kartę Strona główna w czacie indywidualnym w aplikacji Google Chat) obiekt
chatzawiera polachat.userichat.eventTimebez pola uniipayload. Gdy użytkownik kliknie przycisk na karcie strony głównej, obiekt zdarzenia zawierachat.buttonClickedPayloadorazcommonEventObject.parameters(icommonEventObject.formInputs, jeśli karta zawiera dane wejściowe formularza). - W przypadku interakcji w pokoju i wiadomości (Dodano do pokoju, Wiadomość, Usunięto z pokoju, Polecenie aplikacji lub interakcje z przyciskami i widżetami) obiekt
chatzawierachat.user,chat.space,chat.eventTimei odpowiednie dane interakcji:messagePayload: zawieraspace,messageiconfigCompleteRedirectUri, gdy użytkownik wysyła wiadomość.addedToSpacePayload: zawieraspace,interactionAddiconfigCompleteRedirectUri, gdy aplikacja Google Chat zostanie dodana do pokoju.removedFromSpacePayload: zawieraspace, gdy aplikacja Google Chat zostanie usunięta z pokoju.buttonClickedPayload: zawieraspace,message,isDialogEventidialogEventType, gdy użytkownik kliknie przycisk na karcie lub w oknie.widgetUpdatedPayload: zawieraspace, gdy użytkownik wchodzi w interakcję z widżetem, np. wpisuje tekst w menu wielokrotnego wyboru z zewnętrznym źródłem danych.appCommandPayload: zawieraspace,message,appCommandMetadata,isDialogEvent,dialogEventTypeiconfigCompleteRedirectUri, gdy użytkownik wywołuje polecenie aplikacji.
Gdy sesje rozmów są włączone w pokoju czatu indywidualnego z aplikacją Google Chat, obiekt space w ładunku interakcji (np. chat.messagePayload.space, chat.addedToSpacePayload.space, chat.buttonClickedPayload.space, chat.widgetUpdatedPayload.space lub chat.appCommandPayload.space) zawiera sessionState (ustawiony na THREAD) i sessionEnableTime, a obiekt thread (chat.messagePayload.message.thread, chat.buttonClickedPayload.message.thread, chat.appCommandPayload.message.thread lub chat.appCommandPayload.thread) identyfikuje wątek sesji (spaces/{space}/threads/{thread}).
Więcej informacji o obiektach zdarzeń dodatków w Google Chat i innych aplikacjach Google Workspace znajdziesz w artykule o obiektach zdarzeń.
Przekaż odpowiedź
W tej sekcji wyjaśniamy, jak aplikacje do Google Chat używają działań do synchronicznego reagowania na interakcje użytkowników.
Aby odpowiedzieć działaniem, aplikacja Google Chat musi odpowiedzieć w ciągu 30 sekund, a odpowiedź musi dotyczyć pokoju, w którym miała miejsce interakcja. Te odpowiedzi synchroniczne nie wymagają uwierzytelniania. Jeśli aplikacja do Google Chat potrzebuje więcej niż 30 sekund lub musi działać poza pokojem, skonfiguruj uwierzytelnianie i odpowiadaj asynchronicznie za pomocą interfejsu Google Chat API.
Aby synchronicznie odpowiadać na interakcje użytkowników, aplikacja Google Chat obsługuje przychodzący obiekt zdarzenia i zwraca jeden z tych obiektów JSON:
DataActions: tworzy lub aktualizuje wiadomości na czacie (CreateMessageAction,UpdateMessageAction) lub dołącza podglądy linków (UpdateInlinePreviewAction) za pomocąchatDataActionMarkup.RenderActions: tworzy, aktualizuje lub zamyka stronę główną lub okno (pushCard,updateCard,endNavigation: "CLOSE_DIALOG") albo udostępnia dynamiczne sugestie dotyczące danych wejściowych w menu wielokrotnego wyboru (modifyCard).AuthorizationError: wyświetla użytkownikom podstawową kartę autoryzacji (basic_authorization_prompt) umożliwiającą zalogowanie się lub uwierzytelnienie w usłudze zewnętrznej.
W tabeli poniżej pokazano, jak aplikacje do Google Chat mogą reagować za pomocą działań. Aplikacje do Google Chat mogą zwracać obiekty JSON bezpośrednio lub tworzyć odpowiedzi za pomocą AddOnResponseService i CardService w Apps Script.
| Odpowiedź aplikacji do obsługi czatu | Wymagane działanie do zwrócenia (JSON) | Wymagane działanie, aby zwrócić (Apps Script) |
|---|---|---|
| wysłać wiadomość lub zaktualizować wiadomość; | DataActions (createMessageAction lub updateMessageAction) |
DataActionsResponse |
| Wyświetlać podgląd linków w wiadomościach wysyłanych przez użytkowników Google Chat w pokoju. | DataActions (updateInlinePreviewAction) |
DataActionsResponse |
| renderować lub aktualizować stronę główną na karcie Strona główna czatu, | RenderActions (pushCard lub updateCard) |
ActionResponse |
| otwieranie, aktualizowanie i zamykanie okna; | RenderActions (pushCard, updateCard lub endNavigation: "CLOSE_DIALOG") |
ActionResponse |
| Aby zbierać informacje z karty lub okna, zasugeruj elementy wyboru na podstawie tego, co użytkownicy wpisują w menu wielokrotnego wyboru. | RenderActions (modifyCard) |
ActionResponse |
| Poproś o konfigurację lub autoryzację usługi zewnętrznej. | AuthorizationError (basic_authorization_prompt) |
AuthorizationException |
Odpowiedz za pomocą wiadomości
Aplikacje do Google Chat mogą odpowiadać wiadomością na dowolne z tych aktywatorów lub interakcji:
- Wyzwalacze wiadomości, np. gdy użytkownicy @wspominają aplikację do Google Chat lub wysyłają do niej wiadomość na czacie.
- Dodanie do pokoju, np. gdy użytkownicy instalują aplikację Google Chat z Google Workspace Marketplace lub dodają ją do pokoju.
- Polecenie aplikacji, np. gdy użytkownicy wywołują polecenie po ukośniku lub szybkie polecenie.
- kliknięcia przycisków na kartach w wiadomościach lub oknach; Na przykład gdy użytkownicy wpisują informacje i klikają przycisk przesyłania.
Aplikacje do Google Chat mogą zawierać w wiadomości dowolne z tych elementów:
- Tekst zawierający hiperlinki, @wzmianki i emotikony. Zobacz Formatowanie wiadomości.
- co najmniej 1 kartę, która może pojawić się w wiadomości lub otworzyć się w nowym oknie jako okno dialogowe; Więcej informacji znajdziesz w artykule Tworzenie kart dla aplikacji Google Chat.
- co najmniej 1 widżet dodatkowy, czyli przycisk, który pojawia się po tekście lub kartach w wiadomości.
Aby odpowiedzieć wiadomością, zwróć DataActions z obiektem CreateMessageAction:
{
"hostAppDataAction": {
"chatDataAction": {
"createMessageAction": {
"message": <var>MESSAGE</var>
}
}
}
}
Zastąp MESSAGE zasobem Message z interfejsu Chat API.
W tym przykładzie aplikacja do Google Chat tworzy i wysyła wiadomość tekstową z wprowadzeniem, gdy zostanie dodana do pokoju, odpowiadając na aktywator Dodano do pokoju za pomocą DataActions:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} req The request object from Google Chat.
* @param {Object} res The response object from the Chat app.
*/
exports.cymbalApp = function cymbalApp(req, res) {
const chatEvent = req.body.chat;
// Send an onboarding message when added to a Chat space
if (chatEvent.addedToSpacePayload) {
res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
'To learn what else I can do, type `/help`.'
}}}}});
}
};
Python
from flask import Flask, request, json
app = Flask(__name__)
@app.route('/', methods=['POST'])
def cymbal_app():
"""Sends an onboarding message when the Chat app is added to a space.
Returns:
Mapping[str, Any]: The response object from the Chat app.
"""
chat_event = request.get_json()["chat"]
if "addedToSpacePayload" in chat_event:
return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
"createMessageAction": { "message": {
"text": 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
'To learn what else I can do, type `/help`.'
}}
}}})
Java
@SpringBootApplication
@RestController
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
/*
* Sends an onboarding message when the Chat app is added to a space.
*
* @return The response object from the Chat app.
*/
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
JsonNode chatEvent = event.at("/chat");
if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
return new GenericJson() { {
put("hostAppDataAction", new GenericJson() { {
put("chatDataAction", new GenericJson() { {
put("createMessageAction", new GenericJson() { {
put("message", new Message().setText(
"Hi, Cymbal at your service. I help you manage your calendar " +
"from Google Chat. Take a look at your schedule today by typing " +
"`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
"To learn what else I can do, type `/help`."
));
} });
} });
} });
} };
}
return new GenericJson();
}
}
Google Apps Script
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Google Chat.
* @return {Object} Response from the Chat app.
*/
function onAddedToSpace(event) {
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
'To learn what else I can do, type `/help`.'
}}}}};
}
Przykładowy kod zwraca tę wiadomość tekstową:
Aktualizowanie wiadomości
Aplikacje do Google Chat mogą też aktualizować wysyłane przez siebie wiadomości. Na przykład aplikacja do Google Chat może zaktualizować wiadomość po przesłaniu przez użytkownika okna lub kliknięciu przycisku na karcie w wiadomości.
Aby zaktualizować wiadomość aplikacji do Google Chat w odpowiedzi na interakcję, zwróć DataActions z UpdateMessageAction:
{
"hostAppDataAction": {
"chatDataAction": {
"updateMessageAction": {
"message": <var>MESSAGE</var>
}
}
}
}
Zastąp MESSAGE zasobem Message z interfejsu Chat API.
Aplikacje do Google Chat mogą też aktualizować wiadomości wysłane przez użytkownika, aby dołączyć kartę podglądu linku za pomocą updateInlinePreviewAction. Więcej informacji znajdziesz w artykule Wyświetlanie podglądu linków.
Odpowiadanie asynchroniczne za pomocą interfejsu Google Chat API
Zamiast zwracać działanie synchronicznie, aplikacje Google Chat mogą potrzebować wywołania interfejsu Google Chat API, aby odpowiedzieć na interakcję lub wysłać wiadomości proaktywne. Na przykład aplikacje do Google Chat muszą wywoływać interfejs Google Chat API, aby wykonywać te czynności:
- odpowiada na interakcję po 30 sekundach (np. po zakończeniu długotrwałego zadania).
- Wysyłaj wiadomości zgodnie z harmonogramem lub wysyłaj powiadomienia o zmianach w zasobach zewnętrznych.
- wykonywać zadań poza pokojem, w którym doszło do interakcji;
- wykonywać w Google Chat zadania, które nie są dostępne jako działania synchroniczne, takie jak wyświetlanie listy pokoi lub dodawanie osób do pokoju;
- wykonywać zadania w imieniu użytkownika Google Chat (co wymaga uwierzytelnienia użytkownika);
Aby uniknąć wyświetlania użytkownikowi komunikatu o błędzie informującego, że aplikacja Google Chat nie odpowiada, gdy odpowiadasz na interakcję po 30 sekundach, musisz potwierdzić otrzymanie obiektu zdarzenia w ciągu 30 sekund, zwracając pustą odpowiedź:
Node.js
async function onEvent(req, res) {
// Trigger asynchronous job that will respond using the Google Chat API.
...
// Respond with an empty response to the Google Chat platform.
return res.send({});
};
Python
def on_event(event) -> dict:
# Trigger asynchronous job that will respond using the Google Chat API.
...
// Respond with an empty response to the Google Chat platform.
return {}
Java
public String onEvent(JsonNode event) {
// Trigger asynchronous job that will respond using the Google Chat API.
...
// Respond with an empty response to the Google Chat platform.
return "{}";
}
Google Apps Script
function onEvent(event) {
// Trigger asynchronous job that will respond using the Google Chat API.
...
// Respond with an empty response to the Google Chat platform.
return null;
}
Aby wysłać wiadomość za pomocą interfejsu Chat API, skonfiguruj uwierzytelnianie i wywołaj metodę spaces.messages.create. Instrukcje znajdziesz w artykule Wysyłanie wiadomości. Przewodniki dotyczące korzystania z dodatkowych metod interfejsu Chat API znajdziesz w omówieniu interfejsu Chat API.
Powiązane artykuły
- Konfigurowanie interfejsu Google Chat API
- Wyślij wiadomość
- Odpowiadanie na polecenia
- Otwieranie interaktywnych okien
- Odczytywanie danych formularza wprowadzonych przez użytkowników na kartach
- Linki do podglądu
- Tworzenie strony głównej aplikacji Google Chat
- Porządkowanie rozmów w sesje
- Weryfikowanie żądań z Google Chat
- Testowanie funkcji interaktywnych aplikacji do Google Chat
Aplikacje do Google Chat, które nie są dodatkami: odbieranie interakcji użytkowników i odpowiadanie na nie.
Aplikacje do Google Chat, które nie są dodatkami do Google Workspace, otrzymują zdarzenia interakcji z interfejsem Chat API (Event) zamiast obiektów zdarzeń dodatków do Google Workspace (EventObject) i odpowiadają, zwracając zasób Message zamiast działania.
Aby przekształcić aplikację Google Chat, która nie jest dodatkiem, na platformę dodatków do Google Workspace, zapoznaj się z artykułem Przekształcanie aplikacji Google Chat w dodatek do Google Workspace.
Typy zdarzeń interakcji
W przypadku każdego typu interakcji użytkownika Google Chat wysyła do aplikacji Google Chat, która nie jest dodatkiem, obiekt Event, którego typ jest reprezentowany przez pole eventType:
| Interakcja użytkownika | eventType |
Typowa odpowiedź z aplikacji do Google Chat, która nie jest dodatkiem |
|---|---|---|
| Użytkownik wysyła wiadomość do aplikacji do Google Chat. Na przykład @wzmiankuje aplikację do Google Chat lub używa polecenia po ukośniku. | MESSAGE |
Aplikacja do Google Chat odpowiada na podstawie treści wiadomości. Na przykład aplikacja do Google Chat odpowiada na polecenie po ukośniku /about wiadomością, która wyjaśnia, jakie zadania może wykonać. |
| Użytkownik dodaje aplikację do Google Chat do pokoju. | ADDED_TO_SPACE |
Aplikacja do Google Chat wysyła wiadomość powitalną, która wyjaśnia, do czego służy aplikacja i jak użytkownicy w pokoju mogą z niej korzystać. |
| Użytkownik usuwa aplikację do Google Chat z pokoju. | REMOVED_FROM_SPACE |
Aplikacja Google Chat usuwa wszystkie powiadomienia przychodzące skonfigurowane dla pokoju (np. usuwa webhook) i czyści pamięć wewnętrzną. |
| Użytkownik klika przycisk na karcie w wiadomości, oknie lub na stronie głównej aplikacji Google Chat. | CARD_CLICKED |
Aplikacja do Google Chat przetwarza i przechowuje dane przesłane przez użytkownika lub zwraca inną kartę. |
| Użytkownik otwiera stronę główną aplikacji Google Chat, klikając kartę Strona główna w wiadomości 1:1. | APP_HOME |
Aplikacja do Google Chat zwraca statyczną lub interaktywną kartę ze strony głównej. |
| Użytkownik przesyła formularz ze strony głównej aplikacji do Google Chat. | SUBMIT_FORM |
Aplikacja do Google Chat przetwarza i przechowuje dane przesłane przez użytkownika lub zwraca inną kartę. |
| Użytkownik wywołuje polecenie za pomocą szybkiego polecenia. | APP_COMMAND |
Aplikacja do Google Chat odpowiada na podstawie wywołanego polecenia. Na przykład aplikacja do Google Chat odpowiada na polecenie Informacje wiadomością, która wyjaśnia, jakie zadania może wykonywać. |
Aby zobaczyć wszystkie obsługiwane zdarzenia interakcji i przykładowe ładunki JSON, zapoznaj się z artykułem Typy zdarzeń interakcji z aplikacją Google Chat i dokumentacją referencyjną EventType.
Zdarzenia interakcji z okien dialogowych
Jeśli aplikacja do Google Chat, która nie jest dodatkiem, otwiera okna, zdarzenie interakcji zawiera te dodatkowe informacje, których możesz użyć do przetworzenia odpowiedzi:
- Pole
isDialogEventma wartośćtrue. - Atrybut
DialogEventType(REQUEST_DIALOG,SUBMIT_DIALOGlubCANCEL_DIALOG) określa, czy interakcja powoduje otwarcie okna, przesłanie informacji z okna czy zamknięcie okna.
Zdarzenia interakcji w pokojach z sesjami
Gdy sesje rozmowy są włączone w przestrzeni wiadomości prywatnych 1:1 z aplikacją Google Chat, która nie jest dodatkiem, pole najwyższego poziomu space zdarzenia interakcji zawiera space.sessionState (ustawione na THREAD) i space.sessionEnableTime, a message.thread lub thread identyfikuje wątek sesji.
Konfigurowanie aplikacji do Google Chat, która nie jest dodatkiem, do odbierania zdarzeń interakcji
W konsoli Google Cloud otwórz stronę Konfiguracja interfejsu Chat API:
W sekcji Funkcje interaktywne odznacz Utwórz tę aplikację Google Chat jako dodatek do Google Workspace i skonfiguruj Funkcje, pojedynczy punkt końcowy Ustawienia połączenia (adres URL punktu końcowego HTTP, Apps Script, nazwa tematu Cloud Pub/Sub lub Dialogflow), Polecenia, Prompty początkowe, Podglądy linków i Widoczność.
Kliknij Zapisz.
Odpowiadanie za pomocą wiadomości w aplikacji do Google Chat, która nie jest dodatkiem
Aby odpowiedzieć synchronicznie w aplikacji Google Chat, która nie jest dodatkiem, zwróć bezpośrednio obiekt Message. Poniższy przykład odpowiada na zdarzenie interakcji ADDED_TO_SPACE wiadomością tekstową:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} req The event object from Chat API.
* @param {Object} res The response object from the Chat app.
*/
exports.cymbalApp = function cymbalApp(req, res) {
// Send an onboarding message when added to a Chat space
if (req.body.type === 'ADDED_TO_SPACE') {
res.json({
'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
'learn what else I can do, type `/help`.'
});
}
};
Python
from flask import Flask, request, json
app = Flask(__name__)
@app.route('/', methods=['POST'])
def cymbal_app():
"""Sends an onboarding message when the Chat app is added to a space.
Returns:
Mapping[str, Any]: The response object from the Chat app.
"""
event = request.get_json()
if event['type'] == 'ADDED_TO_SPACE':
return json.jsonify({
'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
'learn what else I can do, type `/help`.'
})
return json.jsonify({})
Java
@SpringBootApplication
@RestController
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
/*
* Sends an onboarding message when the Chat app is added to a space.
*
* @return The response object from the Chat app.
*/
@PostMapping("/")
@ResponseBody
public Message onEvent(@RequestBody JsonNode event) {
switch (event.get("type").asText()) {
case "ADDED_TO_SPACE":
return new Message().setText(
"Hi, Cymbal at your service. I help you manage your calendar " +
"from Google Chat. Take a look at your schedule today by typing " +
"`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
"To learn what else I can do, type `/help`.");
default:
return new Message();
}
}
}
Google Apps Script
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app.
*/
function onAddToSpace(event) {
return {
'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
'from Google Chat. Take a look at your schedule today by typing ' +
'`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn ' +
'what else I can do, type `/help`.'
};
}