Z tego przewodnika dowiesz się, jak wywoływać funkcje interfejsu Google Chat API
messages.create()
wykonując dowolną z tych czynności:
- Wysyłaj 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.
- Nazwij wiadomość, aby móc ją określić w innym interfejsie Chat API żądań.
Oprócz wywoływania metody messages.create()
aplikacje Google Chat
mogą tworzyć i wysyłać wiadomości, aby odpowiedzieć na interakcje użytkowników, takie jak opublikowanie
wiadomość powitalną, gdy użytkownik doda aplikację Google Chat do
kosmosu. Gdy odpowiadasz na interakcje, aplikacje do obsługi czatu mogą używać innych
różne typy funkcji komunikacji, w tym interaktywne okna i podgląd linków
i interfejsów. Aby odpowiedzieć użytkownikowi, aplikacja Google Chat wraca
wiadomości są wysyłane synchronicznie i bez wywoływania interfejsu Chat API. Aby się uczyć
o wysyłaniu wiadomości w celu odpowiadania na interakcje, zobacz
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ę messages.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 uwierzytelnisz się jako aplikacja Google Chat, aplikacja Google Chat wyśle wiadomość.
App
.Gdy uwierzytelnisz się jako użytkownik, aplikacja Google Chat wysyła w imieniu użytkownika. Google Chat przypisuje też wartości atrybutów do aplikacji Google Chat, wyświetlając jej nazwę.
Typ uwierzytelniania określa też, które funkcje i interfejsy komunikacji 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
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 pod nazwą. ikonę i opis aplikacji Google Chat.
- Zainstaluj Python Biblioteka klienta interfejsów API Google.
- 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 się uwierzytelnić jako użytkownik, czy jako aplikacja 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.
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. Gdy funkcja uwierzytelniania użytkownika jest włączona, treść wiadomości może zawierać tylko tekst i pomijać funkcje przesyłania wiadomości, które są dostępne tylko komunikatory, w tym interfejsy kart i interaktywne widżety;
Aby wywołać messages.create()
za pomocą uwierzytelniania użytkownika, musisz podać
następujące pola w żądaniu:
- zakres autoryzacji.
który obsługuje uwierzytelnianie użytkowników w przypadku tej metody. W tym przykładzie użyto
zakres
chat.messages.create
. - Zasób
Space
, w którym w którym chcesz opublikować wiadomość. Uwierzytelniony użytkownik musi być członkiem kosmosu. Message
do utworzenia zasobu. Aby zdefiniować treść wiadomości, należy umieścić parametrtext
.
Opcjonalnie możesz dodać takie elementy:
- 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
do rozpocząć wątek lub odpowiedzieć na niego. Jeśli pokój nie użyj podziału na wątki, to pole jest ignorowane.
Aby wysłać SMS-a w imieniu użytkownika, wykonaj te czynności:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_message_user.py
Umieść w pliku
chat_create_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', # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstusermessage', # The text message to create. body={ 'text': '👋 🌎Hello world! Text messages can contain things like:\n\n' + '* Hyperlinks 🔗\n' + '* Emojis 😄🎉\n' + '* Mentions of other Chat users `@` \n\n' 'For details, see the <https://developers.google.com/workspace/chat/format-messages|Chat API developer documentation>.' } ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
Zastąp
SPACE
identyfikatorem pokojuname
. . Aby go uzyskać, wywołaj metodę Metodaspaces.list()
lub z adresu URL pokoju.W katalogu roboczym skompiluj i uruchom przykład:
python3 chat_create_message_user.py
Jeśli pojawi się URL, otwórz go, aby autoryzować aplikacji do obsługi czatu na podstawie zakresu użytego na Twoim użytkownika.
Aplikacja Google Chat tworzy wiadomość, a uwierzytelniona
użytkownik opublikuje wiadomość w pokoju. W interfejsie wiersza poleceń
Chat API zwraca instancję nowego
Message
zasób.
Wysyłanie wiadomości jako aplikacji Google Chat
Z tej sekcji dowiesz się, jak wysyłać wiadomości zawierające tekst, karty i interaktywne widżety za pomocą uwierzytelnianie aplikacji.
Aby wywołać messages.create()
za pomocą uwierzytelniania aplikacji, musisz podać
następujące pola w żądaniu:
- Zakres autoryzacji
chat.bot
. - Zasób
Space
, w którym w którym chcesz opublikować wiadomość. Aplikacja Google Chat musi być z użytkownikiem 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. - 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
do rozpocząć wątek lub odpowiedzieć na niego. Jeśli pokój nie użyj podziału na wątki, to pole jest ignorowane.
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.
Aby wysłać wiadomość opublikowaną jako aplikacja Google Chat, która zawiera tekst, kartę i klikalny przycisk u dołu wiadomości, wykonaj te czynności:
Python
- W katalogu roboczym utwórz plik o nazwie
chat_create_message_app.py
Umieść w pliku
chat_create_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) # Specify the Chat space where the message is posted. Obtain the ID # from the resource name, or from the space's URL. SPACE = 'spaces/SPACE' # Create a Chat message. result = chat.spaces().messages().create( # The Chat space. parent=SPACE, # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstappmessage', # The message to create with text, a card, and a button at the # bottom of the message. body= { 'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.', 'cardsV2': [{ 'cardId': 'myCardId', 'card': { 'header': { 'title': 'About this message', 'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg', 'imageType': 'CIRCLE' }, "sections": [ { "header": "Contents", "widgets": [ { "textParagraph": { "text": "🔡 <b>Text</b> which can include hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️." }}, { "textParagraph": { "text": "🖼️ A <b>card</b> to display visual elements and request information such as text 🔤, dates and times 📅, and selections ☑️." }}, { "textParagraph": { "text": "👉🔘 An <b>accessory widget</b> which adds a button to the bottom of a message." }}, ] }, { "header": "What's next", "collapsible": True, "widgets": [ { "textParagraph": { "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>." }}, { "textParagraph": { "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> the message." }}, { "textParagraph": { "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.' }} ] } ]} }], "accessoryWidgets": [ { "buttonList": { "buttons": [ { "text": "View documentation", "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.", "icon": { "material_icon": { "name": "link" } }, "onClick": { "openLink": { "url": "https://developers.google.com/workspace/chat/create-messages" } } } ] } } ] } ).execute() print(result)
Zastąp
SPACE
identyfikatorem pokojuname
. . Aby go uzyskać, wywołaj metodę Metodaspaces.list()
lub z adresu URL pokoju.W katalogu roboczym skompiluj i uruchom przykład:
python3 chat_create_message_app.py
Aplikacja Google Chat tworzy i publikuje wiadomość w
kosmosu. W interfejsie wiersza poleceń Chat API zwraca wartość
instancji nowej
Message
zasób.
Dodawanie interaktywnych widżetów u dołu wiadomości
W przykładowym kodzie z poprzedniej sekcji Wiadomość w aplikacji Google Chat z klikalnym przyciskiem czyli widżet akcesoriów. Widżety akcesoriów pojawiają się po tekście lub kartach w wiadomości. Możesz używać tych widżetów, aby otrzymywać prompty interakcji z przekazem reklamowym na wiele sposobów, między innymi:
- 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.
- Odrzucanie podobnych wiadomości w aplikacji Google Chat i odkładanie na później w wybranym okresie.
Aby dodać widżety akcesoriów, dołącz
accessoryWidgets[]
w treści żądania i określ co najmniej jeden widżet, który ma być
.
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 użytkownika. w aplikacji Google Chat.
![Widżet akcesoriów.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=19&hl=pl)
Poniżej widać treść żądania, które tworzy wiadomość tekstową z
dwa przyciski. Gdy użytkownik kliknie przycisk, zostanie
funkcja (np. doUpvote
) przetwarza 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",
}
}
}
]
}
}
]
Wyślij wiadomość prywatnie
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 Google Chat 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, określ
privateMessageViewer
w treści żądania. Aby określić użytkownika, ustaw wartość na
zasobu User
,
reprezentuje użytkownika Google Chat. Możesz też użyć usługi
name
parametru
User
zgodnie z poniższym przykładem:
{
"text": "Hello private world!",
"privateMessageViewer": {
"name": "users/USER_ID"
}
}
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ąć w żądaniu te informacje:
Rozpoczynanie wątku lub odpowiadanie w nim
W przypadku pokoi z wątkami: możesz określić, czy nowa wiadomość ma rozpoczynać wątek, czy odpowiadać do istniejącego wątku.
Domyślnie wiadomości utworzone za pomocą interfejsu Chat API rozpoczynają nowy w wątku. Aby łatwiej zidentyfikować wątek i odpowiedzieć na niego później, możesz podać klucz wątku w żądaniu:
- W treści żądania określ
thread.threadKey
. - Określanie parametru 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 zasada jest skonfigurowana, określthreadKey
utworzonej przez siebie. W przeciwnym razie musisz użyć parametruname
w wątku. - Określ parametr zapytania
messageReplyOption
.
Poniższy kod JSON zawiera przykład treści żądania wiadomości tekstowej, która
rozpoczyna wątek lub odpowiada na niego przy użyciu klucza helloWorldThread
:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
Nazywanie wiadomości
Aby pobierać lub określać wiadomość w przyszłych wywołaniach interfejsu API, możesz nazwać wiadomość
ustawiając pole messageId
w żądaniu messages.create()
.
Nazwa wiadomości pozwala ją określić bez konieczności przechowywania
przypisany przez system identyfikator z nazwy zasobu wiadomości (reprezentowany w tagu
name
).
Aby na przykład pobrać wiadomość przy użyciu metody get()
, należy użyć funkcji
nazwę zasobu określającą, którą wiadomość ma zostać pobrana. Nazwa zasobu to
w formacie spaces/{space}/messages/{message}
, gdzie {message}
odpowiada
identyfikator przypisany przez system lub niestandardową nazwę ustawioną podczas tworzenia
.
Aby nazwać wiadomość, określ identyfikator niestandardowy w
messageId
podczas tworzenia wiadomości. Pole messageId
ustawia wartość parametru
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: wymagania:
- Zaczyna się od
client-
. np.client-custom-name
to prawidłowy atrybut niestandardowy Identyfikator, 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 do obsługi czatu nie może używać ten sam niestandardowy identyfikator dla różnych wiadomości.
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 można przetworzyć żądania”. 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
- 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