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 message. 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, w interfejsie Google Chat pojawi się komunikat „Coś poszło nie tak”. lub „Nie można przetworzyć żądania”. 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 Google Chat. 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