W tym przewodniku omawiamy różne sposoby wysyłania wiadomości przez aplikacje Google Chat:
- Wysyłaj SMS-y i wiadomości w czasie rzeczywistym w odpowiedzi na interakcję użytkownika.
- Wysyłaj wiadomości tekstowe i karty asynchronicznie przez wywołanie metody
create
w zasobieMessage
. - Rozpocznij wątek wiadomości lub odpowiedz na niego.
- Wyślij wiadomość i nazwij ją.
Zasób Message
reprezentuje wiadomość tekstową lub kartę w Google Chat. Możesz
create
, get
, update
lub delete
wiadomość w interfejsie Google Chat API, wywołując
odpowiednie metody. Więcej informacji o wiadomościach tekstowych i kartach znajdziesz w artykule Omówienie wiadomości w Google Chat.
Maksymalny rozmiar wiadomości (wraz z tekstem i kartami) to 32 000 bajtów. Jeśli wiadomość przekracza ten rozmiar, aplikacja Google Chat może wysłać więcej niż 1 wiadomość.
Zamiast wywoływać metodę create
w zasobie Message
interfejsu Google Chat API w celu asynchronicznego wysyłania SMS-a lub karty, aplikacje Google Chat mogą też tworzyć wiadomości w odpowiedzi na interakcje użytkowników w czasie rzeczywistym. Odpowiedzi na interakcje użytkowników nie wymagają uwierzytelniania i obsługują inne typy wiadomości, w tym interaktywne okna dialogowe 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 w Google Chat.
- Autoryzacja skonfigurowana dla aplikacji Google Chat
do wysyłania wiadomości asynchronicznych. Do wysyłania wiadomości w czasie rzeczywistym nie jest wymagana konfiguracja autoryzacji.
- Wysłanie wiadomości tekstowej obsługuje obie te metody autoryzacji:
- Uwierzytelnianie użytkowników z zakresem autoryzacji
chat.messages.create
lubchat.messages
. - Uwierzytelnianie aplikacji z zakresem autoryzacji
chat.bot
.
- Uwierzytelnianie użytkowników z zakresem autoryzacji
- Wysyłanie wiadomości karty wymaga uwierzytelniania aplikacji z zakresem autoryzacji
chat.bot
.
- Wysłanie wiadomości tekstowej obsługuje obie te metody autoryzacji:
Python
- Konto Google Workspace z dostępem do Google Chat.
- Python w wersji 3.6 lub nowszej
- Narzędzie do zarządzania pakietami pip
Najnowsze biblioteki klienta Google dla języka Python. Aby je zainstalować lub zaktualizować, uruchom to polecenie w interfejsie wiersza poleceń:
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 w Google Chat.
Autoryzacja skonfigurowana dla aplikacji Google Chat do wysyłania wiadomości asynchronicznych. Do wysyłania wiadomości w czasie rzeczywistym nie jest wymagana konfiguracja autoryzacji.
- Wysłanie wiadomości tekstowej obsługuje obie te metody autoryzacji:
- Uwierzytelnianie użytkowników z zakresem autoryzacji
chat.messages.create
lubchat.messages
. - Uwierzytelnianie aplikacji z zakresem autoryzacji
chat.bot
.
- Uwierzytelnianie użytkowników z zakresem autoryzacji
- Wysyłanie wiadomości karty wymaga uwierzytelniania aplikacji z zakresem autoryzacji
chat.bot
.
- Wysłanie wiadomości tekstowej 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 czatu, skorzystaj z tego quickstart.
- Autoryzacja skonfigurowana dla aplikacji Google Chat
do wysyłania wiadomości asynchronicznych. Do wysyłania wiadomości w czasie rzeczywistym nie jest wymagana konfiguracja autoryzacji.
- Wysłanie wiadomości tekstowej obsługuje obie te metody autoryzacji:
- Uwierzytelnianie użytkowników z zakresem autoryzacji
chat.messages.create
lubchat.messages
. - Uwierzytelnianie aplikacji z zakresem autoryzacji
chat.bot
.
- Uwierzytelnianie użytkowników z zakresem autoryzacji
- Wysyłanie wiadomości karty wymaga uwierzytelniania aplikacji z zakresem autoryzacji
chat.bot
.
- Wysłanie wiadomości tekstowej obsługuje obie te metody autoryzacji:
Wysyłanie SMS-ów
W tej sekcji opisano wysyłanie SMS-ów na 2 sposoby:
- Wysyłaj SMS-y w czasie rzeczywistym w odpowiedzi na interakcję użytkownika.
- Wyślij SMS-a, 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 za każdym razem, gdy zostaje on dodany do pokoju. Sprawdzone metody rozpoczynania współpracy z użytkownikami znajdziesz w artykule na temat pomocy ułatwiającej rozpoczęcie pracy użytkownikom i pokoi.
Aby wysłać SMS-a, gdy użytkownik doda Twoją aplikację Google Chat do pokoju, ta aplikacja zareaguje na zdarzenie interakcji ADDED_TO_SPACE
. Aby odpowiadać SMS-em na zdarzenia interakcji (ADDED_TO_SPACE
), 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 taki komunikat tekstowy:
Asynchroniczne wysyłanie SMS-a
W tej sekcji wyjaśniamy, jak wysyłać SMS-y asynchronicznie z uwierzytelnianiem w aplikacji i uwierzytelnianiem użytkownika.
Aby wysłać SMS-a, podaj w prośbie te informacje:
- W przypadku uwierzytelniania aplikacji określ zakres autoryzacji
chat.bot
. Przy uwierzytelnianiu użytkownika określ zakres autoryzacjichat.messages.create
. - Wywołaj metodę
create
w zasobieMessage
.
Wyślij SMS-a z uwierzytelnianiem aplikacji
Aby wysłać SMS-a z uwierzytelnianiem w aplikacji:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_text_message_app.py
. Umieść w pliku
chat_create_text_message_app.py
ten kod: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
Interfejs Chat API zwraca instancję Message
, która zawiera szczegóły wysyłanej wiadomości.
Wysyłanie SMS-a z uwierzytelnieniem 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ść w pliku
chat_create_text_message_user.py
ten kod: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()
dostępnej w interfejsie Chat API lub z adresu URL pokoju.W katalogu roboczym skompiluj i uruchom przykład:
python3 chat_create_text_message_user.py
Interfejs Chat API zwraca instancję Message
, która zawiera szczegóły wysyłanej wiadomości.
Wyślij wiadomości dotyczące karty
W tej sekcji opisano wysyłanie wiadomości dotyczących kart na 2 sposoby:
- Wysyłaj wiadomość w czasie rzeczywistym w odpowiedzi na interakcję użytkownika.
- Wyślij wiadomość na karcie przez asynchroniczne wywołanie interfejsu Google Chat API.
Wysyłaj wiadomości w czasie rzeczywistym
Aplikacje do obsługi czatu mogą tworzyć karty, aby odpowiedzieć na interakcję użytkownika, na przykład wysłanie przez użytkownika wiadomości do aplikacji Google Chat lub dodanie aplikacji 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 reagowanie na nie.
W tym przykładzie użytkownik wysyła wiadomość do aplikacji Google Chat, a aplikacja Google Chat odpowiada, wysyłając wiadomość w formie karty z nazwą użytkownika i zdjęciem awatara:
Node.js
Python
Google Apps Script
W tym przykładzie wysłanie wiadomości dotyczącej karty wymaga zwrócenia pliku JSON karty. Możesz też użyć usługi kart Apps Script.
Asynchroniczne wysyłanie wiadomości z karty
Aby wysłać wiadomość z karty, podaj w prośbie:
- W przypadku uwierzytelniania aplikacji określ zakres autoryzacji
chat.bot
. Gdy korzystasz z uwierzytelniania użytkownika, nie możesz wysyłać kart. - Wywołaj metodę
create
w zasobieMessage
.
Oto przykładowy komunikat karty:
Aby wysłać wiadomość karty po uwierzytelnieniu w aplikacji:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_card_message.py
. Umieść w pliku
chat_create_card_message.py
ten kod: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 na niego
Aby rozpocząć wątek wiadomości, wyślij wiadomość i pozostaw pole thread.name
puste. Google Chat wypełnia go podczas tworzenia wątku. Opcjonalnie, aby dostosować nazwę wątku, podaj pole thread.threadKey
.
Aby odpowiedzieć w wątku wiadomości, wyślij wiadomość, która określa pole threadKey
lub name
wątku. Jeśli wątek został utworzony przez osobę lub inną aplikację Google Chat, musisz użyć pola thread.name
.
Jeśli nie zostanie znaleziony pasujący wątek, w polu messageReplyOption
możesz określić, czy wiadomość ma rozpocząć nowy wątek, czy nie.
Jeśli parametr messageReplyOption
jest ustawiony, musisz też ustawić thread.name
lub thread.threadKey
.
Aby rozpocząć wątek lub odpowiedzieć na niego, używając pola threadKey
zdefiniowanego jako nameOfThread
:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_message_thread.py
. Umieść w pliku
chat_create_message_thread.py
ten kod: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
Interfejs Chat API zwraca instancję Message
, która zawiera szczegóły wysyłanej wiadomości.
Nazywanie wiadomości
W tej sekcji dowiesz się, jak nazwać wiadomość przez ustawienie jej niestandardowego identyfikatora. Za pomocą identyfikatorów niestandardowych możesz pobierać, aktualizować i usuwać wiadomości. Identyfikatory niestandardowe pozwalają określić wiadomość bez konieczności przechowywania identyfikatora przypisanego przez system w nazwie 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ść przy użyciu metody get()
, należy użyć nazwy zasobu, aby określić, którą wiadomość ma zostać pobrana. Nazwa zasobu ma format spaces/{space}/messages/{message}
, gdzie {message}
to identyfikator przypisany przez system. Jeśli wiadomość ma przez Ciebie nazwę, możesz zastąpić wartość {message}
identyfikatorem niestandardowym.
Aby nazwać wiadomość, podczas jej tworzenia podaj identyfikator niestandardowy w polu messageId
. Pole messageId
ustawia wartość pola clientAssignedMessageId
zasobu Message
.
Możesz nazwać wiadomość tylko podczas jej tworzenia. Nie można nazwać ani modyfikować niestandardowych identyfikatorów istniejących wiadomości. Niestandardowy identyfikator musi spełniać te wymagania:
- Zaczyna się od
client-
. Na przykładclient-custom-name
jest prawidłowym identyfikatorem niestandardowym, alecustom-name
już nie. - Nazwa może składać się z maksymalnie 63 znaków i może zawierać tylko małe litery, cyfry i łączniki.
- Jest unikalna w obrębie pokoju. Aplikacja do obsługi czatu nie może używać tego samego niestandardowego identyfikatora 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ść w pliku
chat_create_named_message.py
ten kod: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 kodzie następujące elementy:
SPACE
: identyfikator pokoju, w którym chcesz opublikować wiadomość. Możesz go 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 u dołu wiadomości
Opcjonalnie do wiadomości możesz dołączyć widżety akcesoriów. Widżety akcesoriów wyświetlają się pod tekstem lub kartami w wiadomości. Za pomocą tych widżetów możesz zachęcać użytkowników do interakcji z Twoją wiadomością na wiele sposobów, na przykład:
- Oceń dokładność lub satysfakcję wiadomości.
- Zgłoś problem z wiadomością lub aplikacją Google Chat.
- Otwórz link do powiązanych treści, np. dokumentacji.
- Odrzuć podobne wiadomości lub odłóż je na jakiś czas w aplikacji Google Chat.
Aby dodać widżety akcesoriów, umieść w wiadomości obiekt accessoryWidgets[]
i wskaż co najmniej 1 AccessoryWidgets
, który chcesz uwzględnić. Wiadomość musi być widoczna dla wszystkich osób w pokoju
(nie można dodawać widżetów z akcesoriami do wiadomości prywatnych).
Poniższy obraz przedstawia aplikację Google Chat, która dodaje wiadomość tekstową z widżetami akcesoriów, aby użytkownicy mogli ocenić działanie aplikacji Google Chat.
Poniższy przykładowy kod pokazuje kod JSON dla tej wiadomości. Gdy użytkownik kliknie jeden z przycisków, interakcja aktywuje odpowiednią funkcję (np. doUpvote
), która przetwarza 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ą prywatnie wysyłać SMS-y i karty, aby były widoczne tylko dla jednego użytkownika w pokoju. Aby wysłać wiadomość prywatną, umieść w niej pole privateMessageViewer
. Wiadomości prywatne mogą wysyłać tylko
aplikacje Google Chat. Aby wysłać wiadomość prywatną
asynchronicznie, musisz użyć uwierzytelniania aplikacji.
Więcej informacji znajdziesz w artykule Wysyłanie prywatnych wiadomości do użytkowników Google Chat.
Rozwiązywanie problemów
Gdy aplikacja lub karta w 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 UI Google Chat nie wyświetla się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat zwraca nieoczekiwany wynik, na przykład wiadomość na karcie.
Mimo że komunikat o błędzie może nie być wyświetlany w interfejsie Google Chat, dostępne są opisowe komunikaty o błędach i dane logów, które pomogą Ci w naprawianiu błędów, gdy logowanie błędów w aplikacjach Google Chat jest włączone. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami w Google Chat.
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 Google Chat
- Wysyłanie wiadomości do Google Chat za pomocą przychodzących webhooków