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 prywatnych wiadomości do określonego użytkownika Google Chat
- Rozpocznij wątek wiadomości lub odpowiedz na niego.
- Nadaj nazwę wiadomości, aby można było ją podać w innych żądaniach interfejsu Chat API.
Maksymalny rozmiar wiadomości (wraz z tekstem i kartami) to 32 000 bajtów. Aby wysyłać wiadomości większe niż 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 do czatu 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. Aby dowiedzieć się więcej o wysyłaniu wiadomości w odpowiedzi na interakcji, patrz Odbieranie interakcji w aplikacji Google Chat i odpowiadanie na nie
Jak Google Chat wyświetla i atrybuty wiadomości utworzone za pomocą interfejsu Chat API
Możesz wywołać metodę create()
za pomocą
uwierzytelnianie aplikacji
i uwierzytelnianie użytkowników.
Google Chat inaczej przypisuje nadawcę wiadomości
w zależności od wybranego typu uwierzytelniania.
Gdy uwierzytnisz się jako aplikacja Google Chat, to właśnie ona wyśle wiadomość.
Gdy uwierzytelnisz się jako użytkownik, aplikacja Google Chat wyśle wiadomość w imieniu tego użytkownika. Google Chat przypisuje też wartości atrybutów do aplikacji do obsługi czatu, wyświetlając jej nazwę.
Typ uwierzytelniania określa też, które funkcje i interfejsy do przesyłania wiadomości które możesz umieścić w wiadomości. Dzięki uwierzytelnianiu aplikacji Aplikacje do obsługi czatu mogą wysyłać wiadomości zawierające tekst sformatowany, z interfejsami kartowymi i interaktywnymi widżetami. Użytkownicy Google Chat mogą wysyłać SMS-y tylko w wiadomościach, więc uwzględniaj tekst tylko podczas tworzenia wiadomości z użyciem uwierzytelniania użytkownika. Aby dowiedzieć się więcej o funkcji przesyłania wiadomości funkcji dostępnych w interfejsie Chat API, zapoznaj się z Omówienie wiadomości w Google Chat
Z tego przewodnika dowiesz się, jak używać dowolnego z tych typów uwierzytelniania do wysyłania wiadomości za pomocą interfejsu Chat API.
Wymagania wstępne
Node.js
- Firmy lub przedsiębiorstwa Konto Google Workspace 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 aplikacji Google Chat.
- Zainstaluj Node.js Biblioteka klienta Cloud.
- Utwórz dane uwierzytelniające na podstawie sposobu uwierzytelniania w interfejsie Google Chat API
żądanie:
- Aby uwierzytelnić się jako użytkownik Google Chat:
utwórz identyfikator klienta OAuth
dane logowania i zapisz je w pliku JSON o nazwie
client_secrets.json
do katalogu lokalnego. - Aby uwierzytelnić się jako aplikacja Google Chat:
utwórz konto usługi
dane logowania i zapisz je w pliku JSON o nazwie
credentials.json
- Aby uwierzytelnić się jako użytkownik Google Chat:
utwórz identyfikator klienta OAuth
dane logowania i zapisz je 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, w którym uwierzytelniony użytkownik Użytkownik dzwoni do aplikacji Google Chat. Aby uwierzytelnić się jako Google Chat, dodaj przez aplikację Google Chat do pokoju.
Python
- Firmy lub przedsiębiorstwa Konto Google Workspace 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 aplikacji Google Chat.
- Zainstaluj Python Biblioteka klienta Cloud.
- Utwórz dane uwierzytelniające na podstawie sposobu uwierzytelniania w interfejsie Google Chat API
żądanie:
- Aby uwierzytelnić się jako użytkownik czatu, utwórz dane logowania OAuth z identyfikatorem klienta i zapisz je w katalogu lokalnym jako plik 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 jako plik JSON o nazwie
- Wybierz zakres autoryzacji w zależności od tego, czy chcesz się uwierzytelnić jako użytkownik, czy jako aplikacja 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 Google Chat, dodaj przez aplikację Google Chat do pokoju.
Java
- Firmy lub przedsiębiorstwa Konto Google Workspace 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 pod nazwą. ikonę i opis aplikacji Google Chat.
- Zainstaluj bibliotekę klienta Cloud w Javie.
- Utwórz dane uwierzytelniające na podstawie sposobu uwierzytelniania w interfejsie Google Chat API
żądanie:
- Aby uwierzytelnić się jako użytkownik czatu, utwórz dane logowania OAuth z identyfikatorem klienta i zapisz je w katalogu lokalnym jako plik 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 jako plik JSON o nazwie
- Wybierz zakres autoryzacji w zależności od tego, czy chcesz się uwierzytelnić jako użytkownik, czy jako aplikacja 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 aplikacji Google Chat.
- Utwórz samodzielny projekt Apps Script. i włącz zaawansowaną usługę czatu.
- W tym przewodniku musisz użyć funkcji użytkownika lub uwierzytelnianie 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 Google Chat, dodaj przez aplikację Google Chat do pokoju.
Wysyłanie wiadomości jako aplikacji 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 do obsługi czatu musi należeć do pokoju.-
Message
do utworzenia zasobu. Aby określić treść wiadomości, możesz uwzględnić tekst sformatowany (text
), co najmniej jeden interfejs karty (cardsV2
), lub jedno i drugie.
Opcjonalnie możesz dodać takie elementy:
- Pole
accessoryWidgets
do uwzględnienia interaktywnych przycisków u dołu wiadomości. - Pole
privateMessageViewer
do Wyślij 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 pokój nie użyj podziału na wątki, 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 u dołu 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. Aby go uzyskać, wywołaj metodę
ListSpaces()
lub z adresu URL pokoju.
Dodawanie interaktywnych widżetów u dołu wiadomości
W pierwszym przykładzie kodu w tym przewodniku funkcja Wiadomość w aplikacji Google Chat z klikalnym przyciskiem czyli widżet akcesoriów. 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łoś problem z wiadomością lub aplikacją Google Chat.
- Otwórz link do powiązanych treści, np. dokumentacji.
- Odrzucanie podobnych wiadomości w aplikacji Google Chat i odkładanie na później w wybranym okresie.
Aby dodać widżety dodatkowe, umieść pole accessoryWidgets[]
w treści prośby i określ co najmniej 1 widżet, który chcesz uwzględnić.
Ten obraz przedstawia aplikację Google Chat, która dołącza do wiadomości wiadomość tekstowa z widżetami akcesoriów, aby użytkownicy mogli ocenić wrażenia z korzystania z urządzenia w aplikacji Google Chat.
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 obsługi czatu mogą wysyłać wiadomości prywatnie, aby wiadomość jest widoczna tylko dla określonego 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ć usługi
name
zasobu User
, jak pokazano w poniższym przykładzie:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
Aby użyć tego przykładu, zastąp USER_ID
z unikalnym identyfikatorem użytkownika, takim jak 12345678987654321
lub
hao@cymbalgroup.com
Więcej informacji o określaniu użytkowników znajdziesz w sekcji
Identyfikowanie i wskazywanie użytkowników Google Chat
Aby wysłać wiadomość prywatną, musisz pominąć te informacje:
Wysyłanie SMS-a w imieniu użytkownika
W tej sekcji wyjaśniono, jak wysyłać wiadomości w imieniu użytkownika za pomocą usługi uwierzytelnianie 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()
za pomocą 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
w którym chcesz opublikować wiadomość. Użytkownik uwierzytelniony musi być członkiem pokoju. - Zasób
Message
, który chcesz utworzyć. Aby określić treść wiadomości, należy umieścić parametrtext
.
Opcjonalnie możesz podać:
- W polu
messageId
, które pozwala nadaj wiadomości nazwę, która ma być używana w innych żądaniach do 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ładowy sposób działania aplikacji Google Chat może wysłać SMS-a w danym pokoju w imieniu uwierzytelnionego użytkownika:
Node.js
Python
Java
Google Apps Script
Aby uruchomić ten przykład, zastąp SPACE_NAME
identyfikatorem z
w pomieszczeniu
name
. Aby go uzyskać, wywołaj metodę
ListSpaces()
lub z adresu URL pokoju.
Rozpocznij wątek lub odpowiedz 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óźniej na niego odpowiedzieć, możesz podać w żądaniu klucz wątku:
- W treści żądania określ
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 odpowiadać w istniejącym wątku:
- W treści żądania umieść 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
.
Ten kod pokazuje przykładowy sposób działania aplikacji Google Chat może wysłać SMS-a rozpoczynającego się od wątku określonego przez 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.
Nazywanie wiadomości
Aby pobierać lub określać wiadomość w przyszłych wywołaniach interfejsu API, możesz nadać jej nazwę
przez ustawienie w żądaniu pola messageId
.
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
.
Możesz nazwać wiadomość tylko podczas jej tworzenia. Nie można nazwać zmienić niestandardowy identyfikator 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ć do 63 znaków i tylko małe litery, cyfry oraz łączników.
- Jest unikalna w obrębie pokoju. Aplikacja Google Chat nie może używać tego samego niestandardowego identyfikatora w przypadku różnych wiadomości.
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 pokojuname
. Identyfikator możesz uzyskać, wywołując metodęListSpaces()
lub korzystając z adresu URL pokoju.MESSAGE-ID
: nazwa wiadomości zaczynającej się odcustom-
. Nie może się powtarzać wśród innych nazw wiadomości utworzonych przez Aplikacja do obsługi czatu w wybranym pokoju.
Rozwiązywanie problemów
Gdy aplikacja Google Chat lub card zwraca błąd, Interfejs czatu wyświetla komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami interfejs Google Chat nie wyświetla się żaden komunikat o błędzie, ale aplikacja Google Chat lub zwraca nieoczekiwany wynik; na przykład wiadomość w formie karty .
Komunikat o błędzie może nie wyświetlać się w interfejsie Google Chat, opisowe komunikaty o błędach i dane dziennika, które pomogą Ci w naprawianiu błędów gdy logowanie błędów aplikacji Google Chat jest włączone. Aby uzyskać pomoc w wyświetlaniu, debugowania i naprawiania błędów, zapoznaj się z artykułem Rozwiązywanie problemów z błędami w Google Chat
Powiązane artykuły
- Użyj kreatora kart, aby: projektowania i wyświetlania podglądu wiadomości kart JSON dla aplikacji Google Chat.
- Formatowanie wiadomości
- Wyświetlanie szczegółów wiadomości
- Wyświetlanie listy wiadomości w pokoju
- Aktualizowanie wiadomości
- 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