Z tego przewodnika dowiesz się, jak używać metody create()
w zasobach Message
interfejsu Google Chat API, aby wykonać jedną z tych czynności:
- wysyłać wiadomości zawierające tekst, karty i interaktywne widżety;
- Wysyłanie wiadomości prywatnych do konkretnego użytkownika Google Chat.
- rozpocząć wątek lub odpowiedzieć na niego,
- Nadaj nazwę wiadomości, aby można było ją podać w innych żądaniach interfejsu Chat API.
Maksymalny rozmiar wiadomości (w tym tekstu lub kart) wynosi 32 tys. bajtów. Aby wysłać wiadomość, która przekracza ten rozmiar, aplikacja Google Chat musi wysłać kilka wiadomości.
Oprócz wywoływania interfejsu API Google Chat w celu tworzenia wiadomości aplikacje Google Chat mogą tworzyć i wysyłać wiadomości jako odpowiedź na działania użytkowników, np. publikować wiadomość powitalną po dodaniu aplikacji Google Chat do pokoju. Odpowiadając na interakcje, aplikacje Google Chat mogą używać innych typów funkcji wiadomości, w tym dialogów interaktywnych i interfejsów podglądu linków. Aby odpowiedzieć użytkownikowi, aplikacja Google Chat zwraca wiadomość synchronicznie, bez wywoływania interfejsu Chat API. Więcej informacji o wysyłaniu wiadomości w odpowiedzi na interakcje znajdziesz w artykule Otrzymywanie i odpowiadanie na interakcje za pomocą aplikacji Google Chat.
Jak Google Chat wyświetla i przypisuje wiadomości utworzone za pomocą interfejsu API czatu
Metodę create()
możesz wywołać, korzystając z uwierzytelniania aplikacji i uwierzytelniania użytkownika.
Google Chat przypisuje nadawcę wiadomości w inny sposób w zależności od typu uwierzytelniania.
Gdy uwierzytnisz się jako aplikacja Google Chat, to ona wysyła wiadomość.
Gdy uwierzytelnisz się jako użytkownik, aplikacja Google Chat wyśle wiadomość w imieniu tego użytkownika. Chat przypisuje też do wiadomości aplikację Google Chat, wyświetlając jej nazwę.
Typ uwierzytelniania określa też, które funkcje i interfejsy wiadomości możesz uwzględnić w wiadomości. Dzięki uwierzytelnianiu aplikacji aplikacje Google Chat mogą wysyłać wiadomości zawierające tekst, interfejsy oparte na kartach i interaktywne widżety. Użytkownicy Google Chat mogą wysyłać tylko tekst, więc podczas tworzenia wiadomości za pomocą uwierzytelniania użytkownika możesz uwzględnić tylko tekst. Więcej informacji o funkcjach przesyłania wiadomości dostępnych w interfejsie Chat API znajdziesz w artykule Omówienie wiadomości w Google Chat.
Z tego przewodnika dowiesz się, jak za pomocą dowolnego typu uwierzytelniania wysłać wiadomość za pomocą interfejsu Chat API.
Wymagania wstępne
Node.js
- Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.
- Skonfiguruj środowisko:
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz i skonfiguruj interfejs Google Chat API, podając nazwę, ikonę i opis swojej aplikacji do obsługi czatu.
- Zainstaluj bibliotekę klienta Cloud dla Node.js.
- Utwórz poświadczenia dostępu na podstawie sposobu uwierzytelniania w żądaniu interfejsu Google Chat API:
- Aby uwierzytelnić się jako użytkownik czatu, utwórz dane logowania OAuth z identyfikatorem klienta i zapisz je w katalogu lokalnym w pliku JSON o nazwie
client_secrets.json
. - Aby uwierzytelnić się jako aplikacja Google Chat, utwórz dane logowania do konta usługi i zapisz je w pliku JSON o nazwie
credentials.json
.
- Aby uwierzytelnić się jako użytkownik czatu, utwórz dane logowania OAuth z identyfikatorem klienta i zapisz je w katalogu lokalnym w pliku JSON o nazwie
- Wybierz zakres autoryzacji w zależności od tego, czy chcesz uwierzytelnić użytkownika czy aplikację Google Chat.
- Pokój Google Chat, którego użytkownik uwierzytelniony lub aplikacja Google Chat jest uczestnikiem. Aby uwierzytelnić się jako aplikacja Google Chat, dodaj ją do pokoju.
Python
- Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.
- Skonfiguruj środowisko:
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz i skonfiguruj interfejs Google Chat API, podając nazwę, ikonę i opis swojej aplikacji do obsługi czatu.
- Zainstaluj bibliotekę klienta Cloud w Pythonie.
- Utwórz poświadczenia dostępu na podstawie sposobu uwierzytelniania w żądaniu interfejsu Google Chat API:
- Aby uwierzytelnić się jako użytkownik czatu, utwórz dane logowania OAuth z identyfikatorem klienta i zapisz je w katalogu lokalnym w pliku JSON o nazwie
client_secrets.json
. - Aby uwierzytelnić się jako aplikacja Google Chat, utwórz dane logowania do konta usługi i zapisz je w pliku JSON o nazwie
credentials.json
.
- Aby uwierzytelnić się jako użytkownik czatu, utwórz dane logowania OAuth z identyfikatorem klienta i zapisz je w katalogu lokalnym w pliku JSON o nazwie
- Wybierz zakres autoryzacji w zależności od tego, czy chcesz uwierzytelnić użytkownika czy aplikację Google Chat.
- Pokój Google Chat, którego użytkownik uwierzytelniony lub wywołująca aplikacja Google Chat jest członkiem. Aby uwierzytelnić się jako aplikacja Google Chat, dodaj ją do pokoju.
Java
- Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.
- Skonfiguruj środowisko:
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz i skonfiguruj interfejs Google Chat API, podając nazwę, ikonę i opis swojej aplikacji do obsługi czatu.
- Zainstaluj bibliotekę klienta Cloud w Javie.
- Utwórz poświadczenia dostępu na podstawie sposobu uwierzytelniania w żądaniu interfejsu Google Chat API:
- Aby uwierzytelnić się jako użytkownik czatu, utwórz dane logowania OAuth z identyfikatorem klienta i zapisz je w katalogu lokalnym w pliku JSON o nazwie
client_secrets.json
. - Aby uwierzytelnić się jako aplikacja Google Chat, utwórz dane logowania do konta usługi i zapisz je w pliku JSON o nazwie
credentials.json
.
- Aby uwierzytelnić się jako użytkownik czatu, utwórz dane logowania OAuth z identyfikatorem klienta i zapisz je w katalogu lokalnym w pliku JSON o nazwie
- Wybierz zakres autoryzacji w zależności od tego, czy chcesz uwierzytelnić użytkownika czy aplikację Google Chat.
- Pokój Google Chat, którego użytkownik uwierzytelniony lub wywołująca aplikacja Google Chat jest członkiem. Aby uwierzytelnić się jako aplikacja Google Chat, dodaj ją do pokoju.
Google Apps Script
- Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.
- Skonfiguruj środowisko:
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz i skonfiguruj interfejs Google Chat API, podając nazwę, ikonę i opis swojej aplikacji do obsługi czatu.
- Utwórz samodzielny projekt Apps Script i włącz zaawansowaną usługę Google Chat.
- W tym przewodniku musisz użyć uwierzytelniania użytkownika lub aplikacji. Aby uwierzytelnić się jako aplikacja Google Chat, utwórz dane logowania konta usługi. Instrukcje znajdziesz w artykule Uwierzytelnianie i autoryzowanie jako aplikacja Google Chat.
- Wybierz zakres autoryzacji w zależności od tego, czy chcesz uwierzytelnić użytkownika czy aplikację Google Chat.
- Pokój Google Chat, którego użytkownik uwierzytelniony lub wywołująca aplikacja Google Chat jest członkiem. Aby uwierzytelnić się jako aplikacja Google Chat, dodaj ją do pokoju.
Wysyłanie wiadomości jako aplikacja Google Chat
W tej sekcji wyjaśniamy, jak wysyłać wiadomości zawierające tekst, karty i interaktywne widżety akcesoriów za pomocą uwierzytelniania aplikacji.
Aby wywołać metodę CreateMessage()
za pomocą uwierzytelniania aplikacji, musisz podać w żądaniu te pola:
chat.bot
zakres autoryzacji.Space
Zasób, w którym chcesz opublikować wiadomość. Aplikacja Google Chat musi być członkiem pokoju.- Zasób
Message
, który chcesz utworzyć. Aby zdefiniować treść wiadomości, możesz dodać tekst multimedialny (text
), jeden lub więcej interfejsów kart (cardsV2
) lub oba te elementy.
Opcjonalnie możesz podać:
- pole
accessoryWidgets
, aby uwzględnić przyciski interaktywne na dole wiadomości. - Pole
privateMessageViewer
, aby wysłać wiadomość prywatnie do określonego użytkownika. - Pole
messageId
, które umożliwia nazwanie wiadomości na potrzeby innych żądań interfejsu API. - pola
thread.threadKey
imessageReplyOption
, aby rozpocząć wątek lub odpowiedzieć na niego. Jeśli wątek nie jest używany, to pole jest ignorowane.
Poniższy kod pokazuje, jak aplikacja Google Chat może wysłać wiadomość opublikowaną jako aplikacja Google Chat, która zawiera tekst, kartę i klikalny przycisk na dole wiadomości:
Node.js
Python
Java
Google Apps Script
Aby uruchomić ten przykład, zastąp wartość SPACE_NAME
identyfikatorem z pola name
w pokoju. Identyfikator możesz uzyskać, wywołując metodę ListSpaces()
lub korzystając z adresu URL pokoju.
Dodawanie interaktywnych widżetów u dołu wiadomości
W pierwszym przykładzie kodu w tym przewodniku wiadomość w aplikacji do obsługi wiadomości zawiera przycisk, który można kliknąć, znajdujący się na dole wiadomości. Jest to widżet akcesorium. Widgety akcesoriów pojawiają się po tekście lub kartach w wiadomości. Za pomocą tych widżetów możesz zachęcać użytkowników do interakcji z wiadomością na wiele sposobów, m.in.:
- ocenić dokładność lub trafność wiadomości;
- Zgłaszanie problemu z aplikacją do wiadomości lub czatu.
- Otwórz link do powiązanych treści, np. dokumentacji.
- odrzucać lub odkładać podobne wiadomości z aplikacji Czat na określony czas;
Aby dodać widżety dodatkowe, umieść pole accessoryWidgets[]
w treści prośby i określ co najmniej 1 widżet, który chcesz dodać.
Na tym obrazie widać aplikację Google Chat, która dołącza do wiadomości tekstowej widżety dodatkowe, aby użytkownicy mogli ocenić swoje wrażenia z korzystania z tej aplikacji.
Poniżej przedstawiono treść żądania, które tworzy wiadomość tekstową z 2 przyciskami pomocniczymi. Gdy użytkownik kliknie przycisk, odpowiednia funkcja (np. doUpvote
) przetworzy tę 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 czatu mogą wysyłać wiadomości prywatne, które są widoczne tylko dla konkretnego użytkownika w pokoju. Gdy aplikacja czatu wysyła wiadomość prywatną, wyświetla etykietę informującą użytkownika, że wiadomość jest widoczna tylko dla niego.
Aby wysłać wiadomość prywatnie za pomocą interfejsu Chat API, w ciele żądania podaj pole privateMessageViewer
. Aby określić użytkownika, ustaw wartość na
User
zasób reprezentujący 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 szablonu, zastąp USER_ID
unikalnym identyfikatorem użytkownika, np. 12345678987654321
lub hao@cymbalgroup.com
. Więcej informacji o wskazywaniu użytkowników znajdziesz w artykule Identyfikowanie i wskazywanie użytkowników Google Chat.
Aby wysłać wiadomość prywatnie, musisz pominąć w prośbie te informacje:
Wysyłanie SMS-a w imieniu użytkownika
W tej sekcji wyjaśniamy, jak wysyłać wiadomości w imieniu użytkownika przy użyciu uwierzytelniania użytkownika. W przypadku uwierzytelniania użytkownika treść wiadomości może zawierać tylko tekst. Nie można używać funkcji wiadomości dostępnych tylko w aplikacjach do czatu, w tym interfejsów kart i interaktywnych widgetów.
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 ramach tej metody. W tym przykładzie użyto zakresu
chat.messages.create
. Space
Zasób, w którym chcesz opublikować wiadomość. Użytkownik uwierzytelniony musi być członkiem pokoju.- Zasób
Message
, który chcesz utworzyć. Aby zdefiniować treść wiadomości, musisz użyć polatext
.
Opcjonalnie możesz podać:
- Pole
messageId
, które pozwala nadać nazwę wiadomości, aby można było jej używać w innych żądaniach interfejsu API. - pola
thread.threadKey
imessageReplyOption
, aby rozpocząć wątek lub odpowiedzieć na niego. Jeśli wątek nie jest używany, to pole jest ignorowane.
Ten kod pokazuje przykładowo, jak aplikacja Google Chat może wysłać wiadomość tekstową w danym pokoju w imieniu uwierzytelnionego użytkownika:
Node.js
Python
Java
Google Apps Script
Aby uruchomić ten przykład, zastąp wartość SPACE_NAME
identyfikatorem z pola name
w pokoju. Identyfikator możesz uzyskać, wywołując metodę ListSpaces()
lub korzystając z adresu URL pokoju.
Rozpoczynanie wątku lub odpowiadanie w wątku
W przypadku pokoi, które korzystają z wątków, możesz określić, czy nowa wiadomość ma tworzyć nowy wątek, czy odpowiadać na istniejący.
Domyślnie wiadomości utworzone za pomocą interfejsu API czatu uruchamiają nowy wątek. Aby ułatwić sobie identyfikację wątku i późniejszą odpowiedź na niego, możesz podać w żądaniu klucz wątku:
- W treści żądania podaj pole
thread.threadKey
. - Określ parametr zapytania
messageReplyOption
, aby określić, co się stanie, jeśli klucz już istnieje.
Aby utworzyć wiadomość, która będzie odpowiedzią na istniejący wątek:
- W treści żądania uwzględnij pole
thread
. Jeśli jest ustawiony, możesz podać utworzony przez siebiethreadKey
. W przeciwnym razie musisz użyćname
wątku. - Określ parametr zapytania
messageReplyOption
.
Poniższy kod pokazuje przykład tego, jak aplikacja Google Chat może wysłać wiadomość tekstową, która rozpoczyna lub odpowiada na dany wątek zidentyfikowany przez klucz danego pokoju w imieniu uwierzytelnionego użytkownika:
Node.js
Python
Java
Google Apps Script
Aby uruchomić ten przykład, zastąp:
THREAD_KEY
: klucz wątku w pokoju lub nazwa wątku, jeśli chcesz utworzyć nowy wątek.SPACE_NAME
: identyfikator z polaname
w pokoju. Identyfikator możesz uzyskać, wywołując metodęListSpaces()
lub korzystając z adresu URL pokoju.
Nazwa 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 umożliwia jej określenie bez konieczności przechowywania przypisanego przez system identyfikatora z nazwy zasobu wiadomości (reprezentowanej w polu name
).
Aby na przykład 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}
to identyfikator przypisany przez system lub nazwa niestandardowa ustawiona podczas tworzenia wiadomości.
Aby nadać nazwę wiadomości, podczas jej tworzenia w polu messageId
wpisz niestandardowy identyfikator. Pole messageId
ustawia wartość pola clientAssignedMessageId
zasobu Message
.
Nazwę wiadomości można nadać tylko podczas jej tworzenia. Nie możesz nadać nazwy ani zmodyfikować identyfikatora niestandardowego istniejących wiadomości. Niestandardowy identyfikator musi spełniać te wymagania:
- Zaczyna się od
client-
. Na przykład identyfikator niestandardowyclient-custom-name
jest prawidłowy, alecustom-name
już nie. - Może zawierać maksymalnie 63 znaki i tylko małe litery, cyfry oraz łączniki.
- jest niepowtarzalna w obrębie przestrzeni; Aplikacja do czatu nie może używać tego samego niestandardowego identyfikatora w różnych wiadomościach.
Ten kod pokazuje przykład tego, jak aplikacja Google Chat może wysłać wiadomość tekstową z identyfikatorem do danego pokoju w imieniu zalogowanego użytkownika:
Node.js
Python
Java
Google Apps Script
Aby uruchomić ten przykład, zastąp:
SPACE_NAME
: identyfikator z polaname
w pokoju. Identyfikator możesz uzyskać, wywołując metodęListSpaces()
lub korzystając z adresu URL pokoju.MESSAGE-ID
: nazwa wiadomości, która zaczyna się odcustom-
. Musi być niepowtarzalna wśród wszystkich nazw wiadomości utworzonych przez aplikację Google Chat w wybranej przestrzeni.
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ć Twojej prośby”. Czasami interfejs czatu nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta czatu powoduje nieoczekiwany wynik, na przykład wiadomość na karcie może się nie wyświetlić.
Komunikat o błędzie może się nie wyświetlać w interfejsie czatu, ale gdy włączone jest rejestrowanie błędów w przypadku aplikacji czatu, dostępne są opisowe komunikaty o błędach i dane dziennika, które pomogą Ci je naprawić. Aby dowiedzieć się, jak wyświetlać, debugować i naprawiać błędy, przeczytaj artykuł Rozwiązywanie problemów z błędami Google Chat.
Powiązane artykuły
- Użyj Kreatora kart, aby zaprojektować i wyświetlić podgląd wiadomości z kartą JSON na potrzeby aplikacji Google Chat.
- Formatowanie wiadomości.
- Wyświetlanie szczegółów wiadomości
- Wyświetlanie wiadomości w pokoju.
- Zaktualizuj wiadomość.
- Usuwanie wiadomości.
- Identyfikowanie użytkowników w wiadomościach Google Chat
- Wysyłanie wiadomości do Google Chat za pomocą przychodzących webhooków.