Wyślij wiadomość

W tym przewodniku omawiamy 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 wiadomości tekstowe i karty, wywołując metodę create w zasobie Message.
  • Rozpocznij wątek wiadomości lub odpowiedz w nim.
  • Wyślij wiadomość i nazwij ją.

Zasób Message reprezentuje tekst lub kartę w Google Chat. Możesz create, get, update lub delete wysłać wiadomość w 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.

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 reagowanie na nie.

Wymagania wstępne

Node.js

Python

  • 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-httplib2 google-auth-oauthlib oauth2client

  • Opublikowana aplikacja Google Chat. Informacje o tym, jak utworzyć i opublikować aplikację, 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.

Google Apps Script

Wysyłanie SMS-ów

W tej sekcji opisano, jak wysyłać wiadomości tekstowe na 2 sposoby:

  • Wysyłając SMS-a w czasie rzeczywistym, odpowiadając 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 do obsługi czatu tworzy i wysyła SMS-a, gdy zostanie dodana do pokoju. Sprawdzone metody dotyczące wprowadzania użytkowników znajdziesz w artykule Pierwsze kroki z użytkownikami i pokojami.

Aby wysłać SMS-a, gdy użytkownik doda Twoją aplikację Google Chat do pokoju, ta aplikacja odpowiada na ADDED_TO_SPACE zdarzenie. Aby odpowiedzieć SMS-em na zdarzenia interakcji z użytkownikiem 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 następujący komunikat tekstowy:

Przykładowy komunikat wprowadzający

Asynchroniczne wysyłanie SMS-ów

Z tej sekcji dowiesz się, jak wysyłać SMS-y asynchronicznie z użyciem uwierzytelniania aplikacji i uwierzytelniania użytkowników.

Aby wysłać SMS-a, podaj w prośbie te informacje:

  • W przypadku uwierzytelniania aplikacji określ zakres autoryzacji chat.bot. W przypadku uwierzytelniania użytkownika określ zakres autoryzacji chat.messages.create.
  • Wywołaj metodę create w zasobie Message.

Wysyłaj SMS-y z uwierzytelnianiem w aplikacji

Aby wysłać SMS-a z uwierzytelnianiem aplikacji:

Python

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

  2. Umieść ten kod w pliku chat_create_text_message_app.py:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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)

  3. W kodzie zastąp SPACE nazwą pokoju, którą możesz uzyskać za pomocą metody spaces.list() w interfejsie Chat API lub z adresu URL pokoju.

  4. 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 wysyłanej wiadomości.

Wyślij SMS-a z uwierzytelnianiem użytkownika

Aby wysłać SMS-a z uwierzytelnianiem użytkownika:

Python

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

  2. Umieść ten kod w pliku 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()

  3. W kodzie zastąp SPACE nazwą pokoju, którą możesz uzyskać za pomocą metody spaces.list() w interfejsie Chat API lub z adresu URL pokoju.

  4. 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 wysyłanej wiadomości.

Wysyłaj wiadomości dotyczące karty

W tej sekcji opisano, jak wysyłać karty na 2 sposoby:

  • Możesz wysłać wiadomość w czasie rzeczywistym, odpowiadając na interakcję użytkownika.
  • Wyślij wiadomość karty, wywołując asynchronicznie interfejs Google Chat API.

Wyślij wiadomość z kartą w czasie rzeczywistym

Aplikacje do obsługi czatu mogą tworzyć wiadomości kart w odpowiedzi na interakcję użytkownika, na przykład gdy użytkownik wysyła 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 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ść z kartą zawierającą nazwę użytkownika i obraz awatara:

aplikacja do obsługi czatu, w której znajduje się karta z wyświetlaną nazwą nadawcy i obrazem awatara;

Node.js

węzeł/awatar-app/index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-app/main.py
from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

Google Apps Script

apps-script/avatar-app/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Asynchroniczne wysyłanie wiadomości karty

Aby wysłać wiadomość z kartą, przekaż 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 zasobie Message.

Oto przykład komunikatu karty:

Wiadomość karty wysłana za pomocą interfejsu Chat API.

Aby wysłać wiadomość przy użyciu uwierzytelniania aplikacji:

Python

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

  2. Umieść ten kod w pliku chat_create_card_message.py:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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)

  3. W kodzie zastąp SPACE nazwą pokoju, którą możesz uzyskać za pomocą metody spaces.list w interfejsie Chat API lub z adresu URL pokoju.

  4. 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 ją podczas tworzenia wątku. Opcjonalnie, aby dostosować nazwę wątku, podaj pole thread.threadKey.

Aby odpowiedzieć w wątku wiadomości, wyślij wiadomość zawierającą pole 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 znaleziono pasującego wątku, w polu messageReplyOption możesz określić, czy wiadomość ma rozpocząć nowy wątek, czy nie.

Aby rozpocząć wątek lub odpowiedzieć na niego, używając pola threadKey określonego jako nameOfThread:

Python

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

  2. Umieść ten kod w pliku chat_create_message_thread.py:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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)

  3. W kodzie zastąp SPACE nazwą pokoju, którą możesz uzyskać za pomocą metody spaces.list w interfejsie Chat API lub z adresu URL pokoju.

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

    python3 chat_create_message_thread.py

Chat API zwraca instancję Message, która zawiera szczegóły wysyłanej wiadomości.

Wysyłanie wiadomości i nadawanie jej nazwy

Ta sekcja wyjaśnia, jak wysłać wiadomość z niestandardową nazwą. Nazwy wiadomości służą do pobierania, aktualizowania lub usuwania wiadomości. Przypisanie niestandardowej nazwy pozwala też aplikacji do obsługi czatu wycofać wiadomość bez zapisywania wiadomości name w treści odpowiedzi zwróconej podczas jej wysyłania.

Przypisanie niestandardowej nazwy nie zastępuje wygenerowanego pola name (nazwy zasobu wiadomości). Zamiast tego ustawia ona niestandardową nazwę w polu clientAssignedMessageId, do którego możesz się odwołać podczas późniejszych operacji, takich jak aktualizowanie lub usuwanie wiadomości.

Nazwy niestandardowe mają następujące wymagania:

  • Rozpocznij od client-. Na przykład nazwa client-custom-name jest prawidłowa, ale custom-name już nie.
  • Może zawierać tylko małe litery, cyfry i łączniki.
  • mieć maksymalnie 63 znaki.
  • Podanie używanej niestandardowej nazwy podczas wysyłania wiadomości zwraca błąd, ale inne metody, takie jak update czy delete, działają zgodnie z oczekiwaniami.

Oto jak wysłać wiadomość i nadać jej nazwę:

Python

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

  2. Umieść ten kod w pliku chat_create_named_message.py:

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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-custom-name',

    # The message to create.
    body={'text': 'Hello, world!'}

).execute()

print(result)

  3. W kodzie zastąp SPACE nazwą pokoju, którą możesz uzyskać za pomocą metody spaces.list w interfejsie Chat API lub z adresu URL pokoju.

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

    python3 chat_create_named_message.py

Chat API zwraca instancję Message, która zawiera szczegóły wysyłanej wiadomości.

Rozwiązywanie problemów

Gdy aplikacja lub karta Google Chat zwróci błąd, w interfejsie czatu pojawi się komunikat „Coś poszło nie tak” lub „Nie udało się przetworzyć Twojego żądania”. Czasami w interfejsie Google Chat nie pojawia się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat mogą dać nieoczekiwany wynik, na przykład komunikat na karcie.

Mimo że komunikat o błędzie może nie wyświetlić 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 rejestrowania błędów w aplikacjach do obsługi czatu. Więcej informacji o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat i rozwiązywanie problemów.