Wysyłanie wiadomości przy użyciu interfejsu Google Chat API

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ść.

Wywołanie metody messages.create() z uwierzytelnianiem aplikacji.
Rysunek 1. Po uwierzytelnieniu aplikacja Google Chat wysyła wiadomość. Aby poinformować, że nadawca nie jest osobą, obok jej nazwy w Google Chat pojawia się 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 po wyświetleniu jej nazwy.

Wywołanie metody messages.create() z uwierzytelnianiem użytkownika.
Rysunek 2. Po uwierzytelnieniu użytkownika użytkownik wysyła wiadomość, a Google Chat wyświetla Nazwa aplikacji do obsługi czatu obok nazwy użytkownika.

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

  • Python w wersji 3.6 lub nowszej
  • narzędzie do zarządzania pakietami pip;
  • Najnowsze biblioteki klienta Google. Aby je zainstalować lub zaktualizować: uruchom następujące polecenie w interfejsie wiersza poleceń: 
    pip3 install --upgrade google-api-python-client google-auth-oauthlib

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;

Wiadomość wysłana z uwierzytelnianiem użytkownika
Rysunek 3. Aplikacja do obsługi czatu wysyła SMS-a na użytkownika.

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ć parametr text .

Opcjonalnie możesz dodać takie elementy:

Aby wysłać SMS-a w imieniu użytkownika, wykonaj te czynności:

Python

  1. W katalogu roboczym utwórz plik o nazwie chat_create_message_user.py

  2. 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 pokoju name. . Aby go uzyskać, wywołaj metodę Metoda spaces.list() lub z adresu URL pokoju.

  3. W katalogu roboczym skompiluj i uruchom przykład:

    python3 chat_create_message_user.py

  4. 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.

Wiadomość wysłana z uwierzytelnianiem aplikacji
Rysunek 4. Aplikacja do obsługi czatu wysyła wiadomość z: tekst, kartę i przycisk akcesorium.

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:

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

  1. W katalogu roboczym utwórz plik o nazwie chat_create_message_app.py

  2. 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 pokoju name. . Aby go uzyskać, wywołaj metodę Metoda spaces.list() lub z adresu URL pokoju.

  3. 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.
Rysunek 5. Wiadomość w aplikacji Google Chat z widżety tekstu i akcesoriów.

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:

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śl threadKey utworzonej przez siebie. W przeciwnym razie musisz użyć parametru name 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, ale custom-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