Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Tworzenie interfejsów Google Chat

Na tej stronie znajdziesz omówienie tworzenia interfejsów użytkownika dodatków do Google Workspace, które rozszerzają Google Chat.

Do tworzenia interfejsów aplikacji Google Chat służą te komponenty dodatku:

Wywołania: sposoby, w jakie użytkownicy Google Chat mogą wywoływać aplikację do obsługi czatu, np. dodając ją do pokoju lub wysyłając do niej wiadomość.
Obiekty zdarzeń: dane, które aplikacje w Google Chat otrzymują z wyzwalaczy lub interakcji z interfejsem.
Działania: sposoby, w jakie aplikacje w Google Chat mogą odpowiadać na interakcje, np. wysyłać wiadomości lub zwracać interfejs użytkownika oparty na kartach.

Aplikacja do obsługi czatu otrzymuje obiekt zdarzenia z wyzwalacza Dodano do pokoju — **Ilustracja 1.** Gdy użytkownik doda aplikację do obsługi czatu w Google Chat do pokoju, uruchomi się wyzwalacz **Dodano do pokoju** i wyśle obiekt zdarzenia. Aby odpowiedzieć wiadomością, aplikacja Google Chat obsługuje obiekt zdarzenia i zwraca działanie, które tworzy wiadomość.

Aplikacje do obsługi czatu mogą tworzyć i wyświetlać karty w tych interfejsach:

Wiadomości, które mogą zawierać tekst, statyczne lub interaktywne karty oraz przyciski.
Strony główne, które pojawiają się na karcie Strona główna w wiadomościach 1:1 z aplikacją do 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, które wyświetlają podgląd informacji o usłudze zewnętrznej.

Aktywatory

W tej sekcji opisujemy wyzwalacze, których dodatki do Google Workspace używają w Google Chat.

Wywołania to konkretne sposoby, w jakie użytkownicy wywołują aplikację do obsługi czatu za pomocą interfejsu Google Chat, np. używając @wzmianek lub poleceń aplikacji.

W tabeli poniżej znajdziesz wyzwalacze Google Chat, ich opis i typowe reakcje aplikacji Google Chat:

Aktywator	Opis	Typowa odpowiedź
Dodano do pokoju	Użytkownik dodaje aplikację do obsługi czatu do pokoju lub administrator Google Workspace instaluje aplikację do obsługi czatu w pokojach do czatu z użytkownikami w organizacji. Więcej informacji o aplikacjach do obsługi czatu zainstalowanych przez administratorów znajdziesz w artykule Instalowanie aplikacji z Marketplace w domenie w dokumentacji pomocy dla administratorów Google Workspace.	Aplikacja Chat wysyła wiadomość wprowadzającą, która wyjaśnia, co robi 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 w jeden z tych sposobów: Wysyła wiadomość w pokoju czatu z aplikacją Chat. wzmianki o aplikacji do obsługi czatu w dowolnym typie pokoju, Wysyła wiadomość zawierającą link pasujący do wzorca adresu URL dla podglądów linków. Wpisuje tekst w menu wielokrotnego wyboru widżetu `selectionInput`.	Aplikacja do czatu odpowiada na podstawie treści wiadomości. Na przykład aplikacja do obsługi czatu odpowiada na polecenie po ukośniku `/about` wiadomością, która wyjaśnia zadania, jakie może wykonać.
Usunięto z pokoju	użytkownik usunie aplikację do obsługi czatu z pokoju lub administrator Google Workspace odinstaluje aplikację do obsługi czatu dla użytkownika w organizacji. Użytkownicy nie mogą usuwać aplikacji Google Chat zainstalowanych przez administratora. Jeśli użytkownik wcześniej zainstalował aplikację Chat, pozostanie ona zainstalowana niezależnie od tego, czy administrator Google Workspace spróbuje ją odinstalować.	Aplikacja Chat usuwa wszystkie przychodzące powiadomienia skonfigurowane dla pokoju (np. usuwa webhook) i czyści pamięć wewnętrzną. Aplikacje do obsługi czatu nie mogą odpowiadać na ten aktywator, ponieważ nie należą już do obszaru.
Polecenie aplikacji	Użytkownik używa polecenia aplikacji w Google Chat.	Aplikacja Chat odpowie na polecenie. Na przykład odpowiada na wiadomość lub otwiera okno.
Strona główna aplikacji	Użytkownik otwiera kartę Strona główna na czacie indywidualnym z aplikacją do obsługi czatu lub wchodzi w interakcję z widżetem na karcie strony głównej.	Aplikacja Chat zwraca obiekt `RenderActions`, który wysyła kartę strony głównej (`pushCard`) lub aktualizuje wyświetlaną kartę strony głównej (`updateCard`).

W przeciwieństwie do innych dodatków musisz skonfigurować wszystkie funkcje wywołania zwrotnego dla tych wyzwalaczy za pomocą interfejsu Google Chat API. Więcej informacji znajdziesz w artykule Konfigurowanie aplikacji do czatu.

Aby odpowiedzieć na aktywator, zapoznaj się z tymi przewodnikami:

Obiekty zdarzeń

Aplikacje do obsługi czatu otrzymują obiekty zdarzeń, gdy uruchamia się wyzwalacz Google Chat lub gdy użytkownicy Google Chat wchodzą w interakcję z interfejsem aplikacji do obsługi czatu (np. klikają przycisk). Obiekt zdarzenia umożliwia używanie danych o interakcjach do reagowania na nie lub aktualizowania interfejsu.

Ładunki obiektów zdarzeń

Każdy obiekt zdarzenia w Google Chat zawiera obiekt commonEventObject z informacjami o gospodarzu i platformie (hostApp: "CHAT", clientPlatform, userLocale, userTimezone i formInputs) oraz obiekt chat zawierający kontekst specyficzny dla Google Chat:

W przypadku wyzwalacza Strona główna aplikacji (gdy użytkownik otwiera kartę Strona główna na czacie indywidualnym z aplikacją obsługującą Google Chat) obiekt chat zawiera pola chat.user i chat.eventTime bez pola payload union. Gdy użytkownik kliknie przycisk na karcie strony głównej, obiekt zdarzenia będzie też zawierać parametr commonEventObject.parameters (oraz commonEventObject.formInputs, jeśli karta zawiera pola formularza).
W przypadku interakcji z pokojem i wiadomościami (Dodano do pokoju, Wiadomość, Usunięto z pokoju, Polecenie aplikacji lub interakcje z przyciskami i widżetami) obiekt chat zawiera chat.user, chat.space, chat.eventTime i odpowiedni ładunek interakcji (messagePayload, addedToSpacePayload, removedFromSpacePayload, buttonClickedPayload, widgetUpdatedPayload lub appCommandPayload).

Więcej informacji o obsłudze obiektów zdarzeń znajdziesz w tych przewodnikach:

Więcej informacji o obiektach zdarzeń dodatku w Chat i innych aplikacjach Google Workspace znajdziesz w artykule Obiekty zdarzeń.

Działania na czacie

W tej sekcji wyjaśniamy, jak aplikacje Google Chat mogą używać działań dodatku, aby odpowiadać na interakcje użytkowników.

Aby odpowiedzieć za pomocą działania dodatku, aplikacja do obsługi czatu musi to zrobić w ciągu 30 sekund, a odpowiedź musi zostać opublikowana w pokoju, w którym doszło do interakcji. W przeciwnym razie aplikacja do obsługi czatu musi skonfigurować uwierzytelnianie i wywołać interfejs Google Chat API, aby odpowiedzieć.

Aplikacje do czatowania mogą obsługiwać interakcje i na nie odpowiadać na wiele sposobów. W wielu przypadkach aplikacje w Chat odpowiadają wiadomością. Aplikacje do obsługi czatu mogą też wyszukiwać informacje w źródle danych, rejestrować informacje o obiekcie zdarzenia lub wykonywać inne czynności. To zachowanie przetwarzania w zasadzie definiuje aplikację Google Chat.

Aby odpowiadać na interakcje użytkowników, aplikacje Google Chat muszą obsługiwać odpowiedni obiekt zdarzenia i zwracać jeden z tych obiektów JSON:

DataActions: tworzy lub aktualizuje dane Google Workspace. Aby wysłać lub zaktualizować wiadomości na czacie, obiekt musi zawierać znaczniki, które definiują zmiany w danych Message, reprezentowane jako chatDataActionMarkup.
RenderActions: tworzenie lub aktualizowanie strony głównej lub okna albo podawanie sugestii dotyczących wpisywania w menu wielokrotnego wyboru.
AuthorizationError: wyświetla użytkownikom kartę autoryzacji, aby mogli się zalogować lub uwierzytelnić w usłudze zewnętrznej. W Google Chat obsługiwana jest tylko podstawowa karta autoryzacji.

W tabeli poniżej znajdziesz informacje o tym, jak aplikacje w Google Chat mogą odpowiadać za pomocą działań. Aplikacje do obsługi czatu mogą zwracać obiekty JSON lub tworzyć odpowiedzi za pomocą funkcji AddOnResponseService Apps Script.

Odpowiedź aplikacji do obsługi czatu	Wymagane działanie do zwrócenia (JSON)	Wymagane działanie, aby zwrócić wartość (Apps Script)
Wysyłanie lub aktualizowanie wiadomości	`DataActions`	`DataActionsResponse`
Wyświetlanie lub aktualizowanie strony głównej na karcie Główna w czacie.	`RenderActions`	`ActionResponse`
Otwieranie, aktualizowanie i zamykanie okien.	`RenderActions`	`ActionResponse`
Aby zbierać informacje z karty lub okna, sugeruj elementy wyboru na podstawie tego, co użytkownicy wpisują w menu wielokrotnego wyboru.	`RenderActions`	`ActionResponse`
Wyświetlanie podglądu linków w wiadomościach wysyłanych przez użytkowników Google Chat w pokoju.	`DataActions`	`DataActionsResponse`

Odpowiadanie za pomocą interfejsu Google Chat API

Zamiast zwracać działanie dodatku, aplikacje do obsługi czatu mogą używać interfejsu Google Chat API do odpowiadania na interakcje. Na przykład aplikacje do obsługi czatu muszą wywoływać interfejs Google Chat API, aby wykonać dowolne z tych działań:

Odpowiadaj na interakcje po 30 sekundach.
wykonywać zadań poza przestrzenią, w której doszło do interakcji,
wykonywać w Google Chat zadań, które nie są dostępne jako działania dodatku; Możesz na przykład wyświetlić listę pokoi, w których użytkownik lub aplikacja do obsługi czatu jest użytkownikiem, albo dodać użytkowników do pokoju.
wykonywać zadania w imieniu użytkownika Chatu (co wymaga uwierzytelnienia użytkownika);

Aby uniknąć wyświetlania użytkownikowi komunikatu o błędzie informującego, że aplikacja Google Chat nie odpowiada, musisz potwierdzić otrzymanie zdarzenia interakcji w ciągu 30 sekund, wysyłając pustą odpowiedź, jak pokazano poniżej:

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

Więcej informacji o uwierzytelnianiu i wywoływaniu interfejsu Chat API znajdziesz w przeglądzie interfejsu Chat API.