W tym przewodniku opisujemy różne sposoby wysyłania wiadomości przez aplikacje Google Chat:
- Wysyłaj SMS-y i karty w czasie rzeczywistym, odpowiadając na interakcje użytkownika.
- Asynchronicznie wysyłaj tekst i karty, wywołując metodę
create
w zasobieMessage
. - Rozpocznij wątek wiadomości lub odpowiedz w nim.
- Wyślij wiadomość i nadaj jej nazwę.
Zasób Message
reprezentuje wiadomość w Google Chat lub tekst lub kartę. Możesz
create
, get
, update
lub delete
wysłać wiadomość w Google Chat API, wywołując odpowiednie metody. Więcej informacji o SMS-ach i kartach znajdziesz w artykule Omówienie wiadomości w Google Chat.
Maksymalny rozmiar wiadomości (w tym tekstu i kart) to 32 000 bajtów. Jeśli rozmiar wiadomości przekracza ten rozmiar, aplikacja Google Chat może wysłać kilka wiadomości.
Zamiast wywoływać metodę create
w zasobie Message
interfejsu Google Chat API w celu asynchronicznego wysyłania wiadomości tekstowej lub karty, aplikacje Google Chat mogą też tworzyć wiadomości w odpowiedzi na interakcje użytkownika w czasie rzeczywistym. Odpowiedzi na interakcje użytkowników nie wymagają uwierzytelniania i obsługują inne typy wiadomości, w tym interaktywne okna i podglądy linków. Więcej informacji znajdziesz w artykule Odbieranie interakcji z aplikacją Google Chat i odpowiadanie na nie.
Wymagania wstępne
Node.js
- konto Google Workspace z dostępem do Google Chat.
- Projekt Google Cloud z włączonym i skonfigurowanym interfejsem Google Chat API. Instrukcje znajdziesz w artykule Tworzenie aplikacji Google Chat.
- Skonfigurowano autoryzację aplikacji Google Chat do wysyłania wiadomości asynchronicznych. Do wysyłania wiadomości w czasie rzeczywistym nie jest wymagana konfiguracja autoryzacji.
- Wysłanie SMS-a obsługuje obie te metody autoryzacji:
- Uwierzytelnianie użytkownika z zakresem autoryzacji
chat.messages.create
lubchat.messages
. - Uwierzytelnianie aplikacji za pomocą zakresu autoryzacji
chat.bot
.
- Uwierzytelnianie użytkownika z zakresem autoryzacji
- Wysłanie wiadomości z kartą wymaga uwierzytelniania aplikacji z zakresem autoryzacji
chat.bot
.
- Wysłanie SMS-a obsługuje obie te metody autoryzacji:
Python
- konto Google Workspace z dostępem do Google Chat.
- Python 3.6 lub nowszy
- Narzędzie do zarządzania pakietami pip
Najnowsze biblioteki klienta Google dla języka Python. Aby je zainstalować lub zaktualizować, uruchom w interfejsie wiersza poleceń to polecenie:
pip3 install --upgrade google-api-python-client google-auth
- Projekt Google Cloud z włączonym i skonfigurowanym interfejsem Google Chat API. Instrukcje znajdziesz w artykule Tworzenie aplikacji Google Chat.
Skonfigurowano autoryzację aplikacji Google Chat do wysyłania wiadomości asynchronicznych. Do wysyłania wiadomości w czasie rzeczywistym nie jest wymagana konfiguracja autoryzacji.
- Wysłanie SMS-a obsługuje obie te metody autoryzacji:
- Uwierzytelnianie użytkownika z zakresem autoryzacji
chat.messages.create
lubchat.messages
. - Uwierzytelnianie aplikacji za pomocą zakresu autoryzacji
chat.bot
.
- Uwierzytelnianie użytkownika z zakresem autoryzacji
- Wysłanie wiadomości z kartą wymaga uwierzytelniania aplikacji z zakresem autoryzacji
chat.bot
.
- Wysłanie SMS-a obsługuje obie te metody autoryzacji:
Google Apps Script
- konto Google Workspace z dostępem do Google Chat.
- Opublikowana aplikacja Google Chat. Aby utworzyć aplikację do obsługi Google Chat, postępuj zgodnie z tym quickstart.
- Skonfigurowano autoryzację aplikacji Google Chat do wysyłania wiadomości asynchronicznych. Do wysyłania wiadomości w czasie rzeczywistym nie jest wymagana konfiguracja autoryzacji.
- Wysłanie SMS-a obsługuje obie te metody autoryzacji:
- Uwierzytelnianie użytkownika z zakresem autoryzacji
chat.messages.create
lubchat.messages
. - Uwierzytelnianie aplikacji za pomocą zakresu autoryzacji
chat.bot
.
- Uwierzytelnianie użytkownika z zakresem autoryzacji
- Wysłanie wiadomości z kartą wymaga uwierzytelniania aplikacji z zakresem autoryzacji
chat.bot
.
- Wysłanie SMS-a obsługuje obie te metody autoryzacji:
Wysyłanie SMS-ów
W tej sekcji opisano, jak wysyłać wiadomości tekstowe na dwa sposoby:
- Wysyłając SMS-a w czasie rzeczywistym, odpowiadając na interakcję użytkownika.
- Wysyłaj SMS-y, wywołując asynchronicznie interfejs Google Chat API.
Wysyłaj SMS-y w czasie rzeczywistym
W tym przykładzie aplikacja Google Chat tworzy i wysyła SMS-a, gdy zostanie dodana do pokoju. Więcej informacji o sprawdzonych metodach wprowadzania użytkowników znajdziesz w artykule Pomoc dla osób i pokoi dotycząca rozpoczynania pracy.
Aby wysłać SMS-a, gdy użytkownik doda Twoją aplikację Google Chat do pokoju, aplikacja Google Chat odpowiada na ADDED_TO_SPACE
zdarzenie interakcji. Aby odpowiedzieć na zdarzenia interakcji (ADDED_TO_SPACE
) przy użyciu SMS-a, użyj tego kodu:
Node.js
/**
* 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. An onboarding message that
* introduces the app and helps people get started with it.
*/
exports.onMessage = function onMessage(req, res) {
if (req.method === 'GET' || !req.body.message) {
res.send(
'Hello! This function is meant to be used in a Google Chat space.');
}
// 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`.'
});
}
};
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. An onboarding message that
* introduces the app and helps people get started with it.
*/
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`.'
}
}
Przykładowy kod zwraca następujący komunikat tekstowy:
Asynchronicznie wysyłanie SMS-ów
Z tej sekcji dowiesz się, jak asynchronicznie wysyłać SMS-y za pomocą uwierzytelniania aplikacji i użytkownika.
Aby wysłać SMS-a, podaj w nim te informacje:
- W przypadku uwierzytelniania aplikacji określ zakres autoryzacji
chat.bot
. W przypadku uwierzytelniania użytkownika określ zakres autoryzacjichat.messages.create
. - Wywołaj metodę
create
w zasobieMessage
.
Wyślij SMS-a z uwierzytelnianiem w aplikacji
Jak wysłać SMS-a przez uwierzytelnienie aplikacji:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_text_message_app.py
. Umieść ten kod w elemencie
chat_create_text_message_app.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
W kodzie zastąp
SPACE
nazwą pokoju, którą możesz uzyskać za pomocą metodyspaces.list()
w interfejsie Chat API lub z adresu URL pokoju.W katalogu roboczym skompiluj i uruchom przykład:
python3 chat_create_text_message_app.py
Chat API zwraca instancję Message
, która zawiera szczegóły wysłanej wiadomości.
Wyślij SMS-a z uwierzytelnianiem użytkownika
Aby wysłać SMS-a z uwierzytelnianiem użytkownika:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_text_message_user.py
. Umieść ten kod w elemencie
chat_create_text_message_user.py
:import os.path from google.auth.transport.requests import Request from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow from googleapiclient.discovery import build from googleapiclient.errors import HttpError # Define your app's authorization scopes. # When modifying these scopes, delete the file token.json, if it exists. SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"] def main(): ''' Authenticates with Chat API via user credentials, then creates a text message in a Chat space. ''' # Start with no credentials. creds = None # Authenticate with Google Workspace # and get user authorization. flow = InstalledAppFlow.from_client_secrets_file( 'client_secrets.json', SCOPES) creds = flow.run_local_server() # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds) # Use the service endpoint to call Chat API. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body={'text': 'Hello, world!'} ).execute() # Prints details about the created membership. print(result) if __name__ == '__main__': main()
W kodzie zastąp
SPACE
nazwą pokoju, którą możesz uzyskać za pomocą metodyspaces.list()
w interfejsie Chat API lub z adresu URL pokoju.W katalogu roboczym skompiluj i uruchom przykład:
python3 chat_create_text_message_user.py
Chat API zwraca instancję Message
, która zawiera szczegóły wysłanej wiadomości.
Wysyłaj wiadomości dotyczące karty
W tej sekcji opisano, jak wysyłać karty na 2 sposoby:
- Wysyłaj wiadomość na karcie w czasie rzeczywistym, odpowiadając na interakcję użytkownika.
- Wyślij wiadomość karty, wywołując asynchronicznie interfejs Google Chat API.
Wysyłaj wiadomość w czasie rzeczywistym
Aplikacje do obsługi czatu mogą tworzyć wiadomości kart w odpowiedzi na interakcję użytkownika, np. gdy wysyła on wiadomość lub dodaje aplikację Google Chat do pokoju. Więcej informacji o reagowaniu na interakcje użytkowników znajdziesz w artykule Odbieranie zdarzeń interakcji z aplikacją Google Chat i odpowiadanie na nie.
W tym przykładzie użytkownik wysyła wiadomość do aplikacji Google Chat, a aplikacja Google Chat odpowiada, wysyłając wiadomość z kartą zawierającą nazwę użytkownika i obraz awatara:
Node.js
Python
Google Apps Script
Ten przykład wysyła wiadomość dotyczącą karty, zwracając kod card JSON. Możesz też użyć usługi kart Apps Script.
Asynchronicznie wysyłaj wiadomość karty
Aby wysłać wiadomość z kartą, podaj w żądaniu te informacje:
- W przypadku uwierzytelniania aplikacji określ zakres autoryzacji
chat.bot
. Nie można wysłać wiadomości karty z uwierzytelnianiem użytkownika. - Wywołaj metodę
create
w zasobieMessage
.
Oto przykład komunikatu na karcie:
Aby wysłać wiadomość z kartą po uwierzytelnieniu w aplikacji:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_card_message.py
. Umieść ten kod w elemencie
chat_create_card_message.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body= { 'cardsV2': [{ 'cardId': 'createCardMessage', 'card': { 'header': { 'title': 'A card message!', 'subtitle': 'Created with the Chat API', 'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png', 'imageType': 'CIRCLE' }, 'sections': [ { 'widgets': [ { 'buttonList': { 'buttons': [ { 'text': 'Read the docs!', 'onClick': { 'openLink': { 'url': 'https://developers.google.com/chat' } } } ] } } ] } ] } }] } ).execute() print(result)
W kodzie zastąp
SPACE
nazwą pokoju, którą możesz uzyskać za pomocą metodyspaces.list
w interfejsie Chat API lub z adresu URL pokoju.W katalogu roboczym skompiluj i uruchom przykład:
python3 chat_create_card_message.py
Rozpoczynanie wątku wiadomości lub odpowiadanie w nim
Aby rozpocząć wątek wiadomości, wyślij wiadomość i pozostaw pole thread.name
puste. Google Chat uzupełni ten wątek podczas tworzenia wątku. Opcjonalnie, aby dostosować nazwę wątku, wypełnij pole thread.threadKey
.
Aby odpowiedzieć w wątku wiadomości, wyślij wiadomość z polem threadKey
lub name
wątku. Jeśli wątek został utworzony przez osobę lub inną aplikację do obsługi czatu, musisz użyć pola thread.name
.
Jeśli nie uda się znaleźć pasującego wątku, w polu messageReplyOption
możesz określić, czy wiadomość ma rozpocząć nowy wątek, czy nie.
Jeśli ustawiona jest wartość messageReplyOption
, musisz też ustawić wartość thread.name
lub thread.threadKey
.
Aby rozpocząć wątek lub odpowiedzieć w nim, korzystając z pola threadKey
zdefiniowanego jako nameOfThread
:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_message_thread.py
. Umieść ten kod w elemencie
chat_create_message_thread.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Whether to start a thread or reply to an existing one. # # Required when threading is enabled in a space unless starting a # thread. Ignored in other space types. Threading is enabled when # space.spaceThreadingState is THREADED_MESSAGES. # # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread # if one exists, otherwise it starts a new one. messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD', # The message body. body={ # The message to create. 'text': 'Start or reply to another message in a thread!', # The thread to start or reply to. 'thread': { 'threadKey': 'nameOfThread' } } ).execute() print(result)
W kodzie zastąp
SPACE
nazwą pokoju, którą możesz uzyskać za pomocą metodyspaces.list
w interfejsie Chat API lub z adresu URL pokoju.W katalogu roboczym skompiluj i uruchom przykład:
python3 chat_create_message_thread.py
Chat API zwraca instancję Message
, która zawiera szczegóły wysłanej wiadomości.
Nazywanie wiadomości
W tej sekcji dowiesz się, jak nazwać wiadomość, ustawiając dla niej niestandardowy identyfikator. Za pomocą identyfikatorów niestandardowych możesz pobierać, aktualizować i usuwać wiadomości. Identyfikatory niestandardowe pozwalają określić wiadomość bez konieczności zapisywania identyfikatora przypisanego do systemu z nazwy zasobu wiadomości (reprezentowanej w polu name
). Nazwa zasobu jest generowana w treści odpowiedzi podczas tworzenia wiadomości.
Aby na przykład pobrać wiadomość za pomocą metody get()
, należy użyć nazwy zasobu do określenia, która wiadomość ma zostać pobrana. Nazwa zasobu ma format spaces/{space}/messages/{message}
, gdzie {message}
reprezentuje identyfikator przypisany przez system. Jeśli nadasz wiadomości nazwę, możesz zastąpić wartość {message}
identyfikatorem niestandardowym.
Aby nazwać wiadomość, podczas jej tworzenia w polu messageId
podaj identyfikator niestandardowy. Pole messageId
ustawia wartość pola clientAssignedMessageId
zasobu Message
.
Wiadomość możesz nazwać tylko podczas jej tworzenia. Niestandardowych identyfikatorów nie można zmieniać dla istniejących wiadomości. Identyfikator niestandardowy musi spełniać te wymagania:
- Zaczyna się od
client-
. Na przykładclient-custom-name
jest prawidłowym identyfikatorem niestandardowym, alecustom-name
już nie. - Zawiera do 63 znaków i tylko małe litery, cyfry i łączniki.
- jest niepowtarzalna w obrębie pokoju, Aplikacja do obsługi czatu nie może używać tego samego identyfikatora niestandardowego dla różnych wiadomości.
Aby wysłać wiadomość z niestandardowym identyfikatorem:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_named_message.py
. Umieść ten kod w elemencie
chat_create_named_message.py
:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message with a custom name. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Custom name for the message used to facilitate later operations. messageId='client-NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
Zastąp w nim ten fragment kodu:
SPACE
: identyfikator pokoju, w którym chcesz opublikować wiadomość, który możesz uzyskać za pomocą metodyspaces.list
w interfejsie Chat API lub z adresu URL pokoju.NAME
: niestandardowa nazwa wiadomości.
W katalogu roboczym skompiluj i uruchom przykład:
python3 chat_create_named_message.py
Interfejs Chat API zwraca instancję Message
.
Dodawanie interaktywnych widżetów na dole wiadomości
Opcjonalnie możesz dołączać wiadomości za pomocą widżetów akcesoriów. Widżety akcesoriów pojawiają się po tekście lub kartach w wiadomości. Dzięki tym widżetom możesz zachęcać użytkowników do interakcji z Twoją wiadomością na wiele sposobów, w tym:
- Oceń dokładność lub satysfakcję wiadomości.
- Zgłoś problem z wiadomością lub aplikacją Google Chat.
- Otwórz link do powiązanej treści, np. dokumentacji.
- Możesz zamknąć lub odłożyć podobne wiadomości w aplikacji Google Chat na określony czas.
Aby dodać widżety akcesoriów, umieść w wiadomości obiekt accessoryWidgets[]
i określ co najmniej 1 element AccessoryWidgets
, który chcesz dołączyć. Wiadomość musi być widoczna dla wszystkich osób w pokoju (nie można dodawać widżetów akcesoriów do wiadomości prywatnych).
Poniższy obraz przedstawia aplikację do obsługi czatu, która dodaje wiadomość tekstową z widżetami akcesoriów, aby użytkownicy mogli ocenić swoje wrażenia z używania tej aplikacji.
Poniższy przykładowy kod pokazuje kod JSON tej wiadomości. Gdy użytkownik kliknie jeden z przycisków, interakcja uruchomi odpowiednią funkcję (np. doUpvote
) przetwarzającą ocenę.
"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łaj wiadomości prywatnie
Aplikacje do obsługi czatu mogą wysyłać prywatne wiadomości tekstowe i kartkowe, aby wiadomości były widoczne tylko dla jednego użytkownika w pokoju. Aby wysłać wiadomość prywatnie, musisz określić pole privateMessageViewer
w wiadomości. Wiadomości prywatne mogą wysyłać tylko aplikacje do obsługi czatu. Aby asynchronicznie wysyłać wiadomość prywatną, musisz użyć uwierzytelniania aplikacji.
Szczegółowe informacje znajdziesz w artykule Wysyłanie wiadomości prywatnych do użytkowników Google Chat.
Rozwiązywanie problemów
Gdy aplikacja lub karta Google Chat zwróci błąd, interfejs czatu wyświetli komunikat „Coś poszło nie tak” lub „Nie udało się przetworzyć Twojej prośby”. Czasami w interfejsie Google Chat nie pojawia się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat zwraca nieoczekiwany wynik, na przykład komunikat na karcie może się nie pojawić.
Mimo że komunikat o błędzie może nie wyświetlać się w interfejsie Google Chat, dostępne są opisowe komunikaty o błędach i dane dziennika, które pomogą Ci naprawić błędy występujące po włączeniu logowania błędów w aplikacjach do obsługi czatu. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat i ich naprawianie.
Powiązane artykuły
- Formatowanie wiadomości
- Sprawdzanie szczegółów wiadomości
- Wyświetlanie listy wiadomości w pokoju
- Aktualizowanie wiadomości
- Usuwanie wiadomości
- Identyfikowanie użytkowników w wiadomościach w Google Chat
- Wysyłanie wiadomości do Google Chat za pomocą przychodzących webhooków