Tworzenie interfejsów Google Chat

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

W Google Chat dodatki są widoczne dla użytkowników jako aplikacje Google Chat. Więcej informacji znajdziesz w artykule Więcej informacji o rozszerzaniu Google Chat.

Aby tworzyć interfejsy aplikacji Google Chat, możesz używać tych komponentów dodatkowych:

  • Reguły: sposoby, w jakie użytkownicy Google Chat mogą wywoływać aplikację Google Chat, na przykład dodając ją do pokoju lub wysyłając do niej wiadomość.
  • Obiekty zdarzeń: dane, które aplikacje Google Chat otrzymują z wyzwalaczy lub interakcji z interfejsem użytkownika.
  • Czynności: sposoby, w jakie aplikacje do czatu mogą reagować na interakcje, takie jak wysyłanie wiadomości lub zwracanie interfejsu użytkownika opartego na kartach.
Aplikacja do obsługi czatu otrzymuje obiekt zdarzenia z wyzwalacza „dodano do pokoju”.
Ilustracja 1. Gdy użytkownik doda aplikację Google Chat do pokoju, wyzwalacz Dodano do pokoju zostanie uruchomiony i wyśle obiekt zdarzenia. Aby odpowiedzieć wiadomością, aplikacja Google Chat przetwarza obiekt zdarzenia i zwraca działanie, które tworzy wiadomość.

Aplikacje czatu mogą tworzyć i wyświetlać karty w tych interfejsach:

  • Wiadomości mogą zawierać tekst, karty statyczne lub interaktywne oraz przyciski.
  • Okna, czyli karty, które otwierają się w nowym oknie i zwykle proszą użytkowników o przesłanie informacji.
  • Podgląd linków, czyli karty zawierające informacje o usłudze zewnętrznej.

Reguły

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

Wyzwalacze to konkretne sposoby, w jakich użytkownicy uruchamiają aplikację Google Chat za pomocą interfejsu Google Chat, na przykład za pomocą @wzmianek lub poleceń aplikacji.

W tabeli poniżej znajdziesz opisy uruchamiających czaty zdarzeń i działania, jakie zwykle podejmują aplikacje czatu:

Wyzwalacz 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 obsługi czatu zainstalowanych przez administratorów znajdziesz w dokumentacji pomocy dla administratorów Google Workspace w artykule Instalowanie aplikacji z Marketplace w domenie.

 Aplikacja Google Chat wysyła wiadomość powitalną, która wyjaśnia, do czego służy i jak użytkownicy w pokoju mogą z niej korzystać.
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 wiadomościami na czacie.
  • @wzmianki o aplikacji Chat w dowolnym pokoju.
  • Wysyła wiadomość zawierającą link pasujący do wzorca adresu URL podglądu linków.
  • Wpisuje tekst w menu wybierania wielu elementów w widżecie selectionInput.
 Aplikacja Google Chat odpowiada na podstawie treści wiadomości. Na przykład aplikacja Google Chat odpowiada na polecenie /about wiadomością z wyjaśnieniem zadań, które może wykonać.
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 miał wcześniej zainstalowaną aplikację Google Chat, aplikacja ta pozostanie zainstalowana niezależnie od tego, czy administrator Google Workspace spróbuje ją odinstalować.

 Aplikacja Google Chat usuwa wszystkie przychodzące powiadomienia skonfigurowane dla pokoju (np. usuwanie webhooka) i czyści pamięć wewnętrzną. Aplikacje do czatu nie mogą odpowiadać na ten czynnik wiadomościami, ponieważ użytkownicy nie są już członkami pokoju.
Polecenie aplikacji

Użytkownik używa szybkiego polecenia lub polecenia po ukośniku w aplikacji Chat.

 Aplikacja Google Chat reaguje na polecenie. Na przykład: odpowiedzieć wiadomością lub otworzyć okno dialogowe.

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

Aby odpowiedzieć na żądanie, zapoznaj się z tymi przewodnikami:

Obiekty zdarzeń

W tej sekcji definiujemy i omawiamy wszystkie elementy obiektów zdarzeń czatu. Więcej informacji znajdziesz w artykule [GA4] Obiekty zdarzenia.

Obiekt zdarzenia
commonEventObject object (CommonEventObject)
Obiekt zawierający informacje wspólne dla wszystkich obiektów zdarzeń, niezależnie od aplikacji hosta.
chat object (Chat)
Obiekt zawierający wszystkie informacje o interakcjach w Google Chat.

Czat

Czat
chat.user object (User)
Użytkownik Google Chat, który wszedł w interakcję z aplikacją Google Chat.
chat.space object (Space)
Pokój Google Chat, w którym użytkownik wszedł w interakcję z aplikacją Google Chat.
chat.eventTime

string (Timestamp format)

Czas, w którym nastąpiła interakcja.

Pole unii payload.

payload może być tylko jednym z tych elementów:
chat.messagePayload

object (MessagePayload)

Dane, które aplikacje Google Chat otrzymują z wyzwalacza typu wiadomość.
chat.addedToSpacePayload

object (AddedToSpacePayload)

Dane, które aplikacje Google Chat otrzymują z trybu dodania do pokoju.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Dane, które aplikacje czatu otrzymują z usuniętego z pokoju.
chat.buttonClickedPayload

object (ButtonClickedPayload)

Dane, które aplikacje do czatu otrzymują, gdy użytkownicy klikną przycisk w wiadomości lub na karcie. Jeśli użytkownik kliknie przycisk, aby przesłać informacje, obiekt commonEventObject.formInputs będzie zawierać wartości zebrane od użytkownika. Więcej informacji znajdziesz w artykule Zbieranie informacji od użytkowników Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

Dane, które aplikacje Google Chat otrzymują, gdy użytkownicy wpisują tekst w menu wielowyboru widżetu selectionInput. Aplikacje do czatu mogą używać tego obiektu zdarzenia do wypełniania sugerowanych pozycji z dynamicznego źródła danych. Aby na przykład wypełnić zgłoszenia z zewnętrznego źródła danych, aplikacja do czatu może wysłać zapytanie do tego źródła na podstawie tego, co użytkownik wpisze w menu, a potem zwrócić wszystkie pasujące zgłoszenia jako elementy do wyboru.

Obiekt CommonEventObject.parameters['autocomplete_widget_query'] zawiera ciąg tekstowy, który użytkownik wpisze w menu.

chat.appCommandPayload

object (AppCommandPayload)

Dane, które aplikacje do obsługi czatu otrzymują, gdy użytkownik użyje polecenia z aplikacji do obsługi czatu.

Ładunek

W zależności od typu interakcji zdarzenie zawiera ładunek z co najmniej 1 zasobem interfejsu API czatu.

Ładunek wiadomości
MessagePayload
chat.messagePayload.message object (Message)
Wiadomość w Google Chat, która wywołała zdarzenie.
chat.messagePayload.space object (Space)
Pokój czatu, w którym użytkownik wysłał wiadomość, która wywołała aplikację Google Chat.

Dodano do ładunku przestrzeni
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
Pokój Google Chat, do którego użytkownik dodał lub zainstalował aplikację Google Chat.

Gdy administratorzy instalują aplikacje Google Chat, pole space.adminInstalled jest ustawione na true.

chat.addedToSpacePayload.interactionAdd boolean
Czy użytkownik dodał aplikację Google Chat do pokoju, używając wiadomości. Na przykład @mentions the Chat app or uses a slash command. Jeśli true, Google Chat wysyła kolejny obiekt zdarzenia z messagePayload, który zawiera informacje o wiadomości.

Usunięto z ładunku pokoju
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
Pokój Google Chat, z którego użytkownik usunął lub odinstalował aplikację Google Chat.

Gdy administratorzy odinstalują aplikacje Google Chat, pole space.adminInstalled zostanie ustawione na false.

Ładunek kliknięcia przycisku
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
Wiadomość na czacie zawierająca przycisk, który użytkownik kliknął.
chat.buttonClickedPayload.space object (Space)
Pokój czatu, w którym użytkownik kliknął przycisk w wiadomości z aplikacji Google Chat.
chat.buttonClickedPayload.isDialogEvent boolean
Czy użytkownik kliknął przycisk, aby wejść w interakcję z oknem.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
Jeśli isDialogEvent to true, typ interakcji w dialogu.

Wyliczenie DialogEventType.

Wartość dialogEventType może mieć tylko jedną z tych wartości:
TYPE_UNSPECIFIED Wartość domyślna. Nie określono.
REQUEST_DIALOG Użytkownik prosi o dialog. Może to być na przykład użycie polecenia / lub kliknięcie przycisku w wiadomości.
SUBMIT_DIALOG Użytkownik klika element interaktywny w dialogu. Na przykład użytkownik wypełnia informacje w oknie dialogowym i klika przycisk, aby je przesłać.

Payload zaktualizowanego widżetu
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
Pokój czatu, w którym miała miejsce interakcja.

Ładunek polecenia aplikacji
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Metadane o tym, którego polecenia użył użytkownik i jak je aktywował.
chat.appCommandPayload.space object (Space)
Pokój czatu, w którym użytkownik użył polecenia.
chat.appCommandPayload.thread object (Thread)
Jeśli interakcja miała miejsce w wątku, to wątku czatu, w którym użytkownik użył polecenia.
chat.appCommandPayload.message object (Message)
Wiadomość wysłana przez użytkownika za pomocą polecenia po ukośniku.
chat.appCommandPayload.configCompleteRedirectUri string
Jeśli polecenie wymaga autoryzacji lub konfiguracji, adres URL, do którego użytkownik zostanie przekierowany po zakończeniu procesu poza Google Chat.
chat.appCommandPayload.isDialogEvent boolean
Czy polecenie otwiera okno.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Typ interakcji z oknem dialogowym.

Wyliczenie DialogEventType.

Wartość dialogEventType może mieć tylko jedną z tych wartości:
TYPE_UNSPECIFIED Wartość domyślna. Nie określono.
REQUEST_DIALOG Użytkownik prosi o dialog. Może to być na przykład użycie polecenia / lub kliknięcie przycisku w wiadomości.
SUBMIT_DIALOG Użytkownik klika element interaktywny w dialogu. Na przykład użytkownik wypełnia informacje w oknie dialogowym i klika przycisk, aby je przesłać.
Metadane polecenia aplikacji
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

Identyfikator polecenia.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
Typ polecenia.

Wyliczenie AppCommandType.

Wartość AppCommandType może mieć tylko jedną z tych wartości:
APP_COMMAND_TYPE_UNSPECIFIED Wartość domyślna. Nie określono.
SLASH_COMMAND Użytkownik używa polecenia, wysyłając wiadomość, która zaczyna się od ukośnika /.

Działania na czacie

W tej sekcji wyjaśniamy, jak aplikacje do obsługi czatu mogą używać czynności dodatkowych do reagowania na interakcje użytkowników.

Aby odpowiedzieć za pomocą działania dodatku, aplikacja Google Chat musi odpowiedzieć w ciągu 30 sekund, a odpowiedź musi zostać opublikowana w pokoju, w którym miała miejsce interakcja. W przeciwnym razie aplikacja Google Chat musi skonfigurować uwierzytelnianie i wywołać interfejs Google Chat API, aby odpowiedzieć.

Aplikacje do czatu mogą obsługiwać interakcje i reagować na nie na wiele sposobów. W wielu przypadkach aplikacje do czatu odpowiadają wiadomością. Aplikacje do czatu mogą też wyszukiwać informacje w źródłach danych, rejestrować informacje o obiekcie zdarzenia lub po prostu o czymkolwiek innym. To zachowanie definiuje aplikację Google Chat.

Aby odpowiadać na interakcje użytkownika, aplikacje do obsługi czatu muszą obsługiwać odpowiedni obiekt zdarzenia i zwracać jeden z tych obiektów JSON:

Pożądana odpowiedź aplikacji do obsługi czatu Wymagane działanie w przypadku zwrotu
Wyślij lub zaktualizuj wiadomość. DataActions
Otwórz, zaktualizuj lub zamknij okno. RenderActions
Aby zbierać informacje z karty lub okna dialogowego, sugeruj elementy wyboru na podstawie tego, co użytkownicy wpisują w menu wielokrotnego wyboru. RenderActions
Podgląd linków w wiadomościach wysyłanych przez użytkowników czatu w pokoju. DataActions

Odpowiadanie za pomocą interfejsu Google Chat API

Zamiast zwracać działanie dodatku aplikacje czatu mogą potrzebować interfejsu Google Chat API do odpowiedzi na interakcję. Na przykład aplikacje czatu muszą wywoływać interfejs Google Chat API, aby:

  • Odpowiedz na interakcję w ciągu 30 sekund.
  • wykonywać czynności poza pokojem, w którym doszło do interakcji;
  • wykonywanie w Google Chat zadań, które nie są dostępne jako dodatki. Możesz na przykład wyświetlić listę pokoi, w których znajduje się użytkownik lub aplikacja do obsługi czatu, albo dodać użytkowników do pokoju.
  • Wykonywanie zadań w imieniu użytkownika Google Chat (wymaga uwierzytelnienia użytkownika).

Więcej informacji o uwierzytelnianiu i wywoływaniu interfejsu Chat API znajdziesz w artykule Przegląd interfejsu Chat API.