Wyślij wiadomość

W tym przewodniku wyjaśniamy 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 SMS-y i wiadomości z kartą, wywołując metodę create w zasobie Message.
  • Rozpocznij wątek wiadomości lub odpowiedz na nią.
  • Wyślij wiadomość i nadaj jej nazwę.

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 SMS-ach 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ż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 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 do 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. Aby utworzyć i opublikować aplikację do obsługi czatu, przeczytaj artykuł Tworzenie aplikacji Google Chat.

  • Skonfigurowano autoryzację wysyłania wiadomości asynchronicznych przez aplikację do obsługi czatu. 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ć SMS-y na 2 sposoby:

  • Wysyłaj SMS-y w czasie rzeczywistym, odpowiadając na interakcje użytkownika.
  • Wyślij wiadomość tekstową, 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 za każdym razem, gdy zostanie dodana do pokoju. Więcej informacji o sprawdzonych metodach wdrażania użytkowników znajdziesz w tym artykule.

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

Przykładowy komunikat wprowadzający.

Niesynchroniczne wysyłanie SMS-ów

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

Aby wysłać SMS-a, podaj w żądaniu te informacje:

  • Przy uwierzytelnianiu 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.

Wyślij SMS-a 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

Interfejs 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

  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

Interfejs 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:

  • Wyślij wiadomość z kartą w czasie rzeczywistym, odpowiadając na interakcję użytkownika.
  • Wyślij wiadomość na karcie, wywołując asynchronicznie interfejs Google Chat API.

Wysyłaj wiadomość z kartą w czasie rzeczywistym

Aplikacje do obsługi czatu mogą tworzyć wiadomości kart w odpowiedzi na interakcje użytkownika, na przykład gdy użytkownik wysyła wiadomość lub dodaje aplikację do obsługi czatu do pokoju. Więcej informacji o reagowaniu na interakcje użytkowników znajdziesz w artykule Odbieranie zdarzeń interakcji z aplikacją do 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ść na kartę zawierającą nazwę użytkownika i obraz awatara:

Aplikacja do obsługi czatu odpowiada, wysyłając kartę 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 {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/awatar-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 = {
      "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 {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Niesynchroniczne wysyłanie wiadomości z kartą

Aby wysłać wiadomość z kartą, przekaż w swojej prośbie te dane:

  • Przy uwierzytelnianiu aplikacji określ zakres autoryzacji chat.bot. Nie można wysłać karty z uwierzytelnianiem użytkownika.
  • Wywołaj metodę create w zasobie Message.

Oto przykład komunikatu na karcie:

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

Aby wysłać wiadomość z kartą po zastosowaniu uwierzytelnienia w 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 na nie

Aby rozpocząć wątek wiadomości, wyślij wiadomość i pozostaw pole thread.name puste. W Google Chat zostanie on uzupełniony 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 zostanie znaleziony żaden wątek, możesz określić w polu messageReplyOption, czy wiadomość ma rozpocząć nowy wątek, czy nie.

Aby rozpocząć wątek lub odpowiedzieć na niego, używając pola threadKey zdefiniowanego 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

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

Wysyłanie i nazywanie wiadomości

W tej sekcji dowiesz się, jak wysłać wiadomość z niestandardową nazwą. Nazwy wiadomości służą do pobierania, aktualizowania lub usuwania wiadomości. Dzięki temu aplikacja do obsługi czatu będzie też mogła cofnąć wiadomość bez zapisywania jej 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 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:

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

Aby wysłać i nazwać wiadomość:

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

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

Rozwiązywanie problemów

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

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 w rozwiązywaniu problemów pojawiających się po włączeniu rejestrowania błędów w aplikacjach do obsługi czatu. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat i ich rozwiązywanie.