Mengirim pesan

Panduan ini menjelaskan berbagai cara aplikasi Google Chat dapat mengirim pesan:

  • Kirim pesan teks dan kartu secara real time dengan merespons interaksi pengguna.
  • Kirim pesan teks dan kartu secara asinkron dengan memanggil metode create pada resource Message.
  • Memulai atau membalas rangkaian pesan.
  • Kirim dan beri nama pesan.

Resource Message mewakili pesan teks atau kartu di Google Chat. Anda dapat create, get, update, atau delete pesan di Google Chat API dengan memanggil metode yang sesuai. Untuk mempelajari pesan teks dan kartu lebih lanjut, lihat Ringkasan pesan Google Chat.

Daripada memanggil metode create di resource Message Google Chat API untuk mengirim pesan teks atau kartu secara asinkron, aplikasi Google Chat juga dapat membuat pesan untuk merespons interaksi pengguna secara real time. Respons terhadap interaksi pengguna tidak memerlukan autentikasi dan mendukung jenis pesan lainnya, termasuk dialog interaktif dan pratinjau link. Untuk mengetahui detailnya, baca Menerima dan merespons interaksi dengan aplikasi Google Chat Anda.

Prasyarat

Node.js

Python

  • Akun Google Workspace dengan akses ke Google Chat.
  • Python 3.6 atau yang lebih baru
  • Alat pengelolaan paket pip
  • Library klien Google terbaru untuk Python. Untuk menginstal atau mengupdatenya, jalankan perintah berikut di antarmuka command line Anda:

    pip3 install --upgrade google-api-python-client google-auth
    
  • Project Google Cloud dengan Google Chat API yang diaktifkan dan dikonfigurasi. Untuk mengetahui langkah-langkahnya, lihat Mem-build aplikasi Google Chat.
  • Otorisasi yang dikonfigurasi untuk aplikasi Chat untuk mengirim pesan asinkron. Tidak diperlukan konfigurasi otorisasi untuk mengirim pesan secara real time.

Apps Script

  • Akun Google Workspace dengan akses ke Google Chat.
  • Aplikasi Chat yang dipublikasikan. Untuk mem-build aplikasi Chat, ikuti quickstart ini.
  • Otorisasi yang dikonfigurasi untuk aplikasi Chat untuk mengirim pesan asinkron. Tidak diperlukan konfigurasi otorisasi untuk mengirim pesan secara real time.

Mengirim pesan teks

Bagian ini menjelaskan cara mengirim pesan teks dalam dua cara berikut:

  • Mengirim pesan teks secara real time dengan merespons interaksi pengguna.
  • Kirim pesan teks dengan memanggil Google Chat API secara asinkron.

Mengirim pesan teks secara real time

Dalam contoh ini, aplikasi Chat Anda membuat dan mengirim pesan teks setiap kali ditambahkan ke ruang. Untuk mempelajari praktik terbaik dalam orientasi pengguna, lihat Membuat orang dan ruang memulai orientasi yang bermanfaat.

Untuk mengirim pesan teks saat pengguna menambahkan aplikasi Chat Anda ke ruang, aplikasi Chat Anda akan merespons peristiwa interaksi ADDED_TO_SPACE. Untuk merespons peristiwa interaksi ADDED_TO_SPACE dengan pesan teks, gunakan kode berikut:

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`.'
    });
  }
};

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`.'
  }
}

Contoh kode akan menampilkan pesan teks berikut:

Contoh pesan orientasi.

Mengirim pesan teks secara asinkron

Bagian berikut menjelaskan cara mengirim pesan teks secara asinkron dengan autentikasi aplikasi dan autentikasi pengguna.

Untuk mengirim pesan teks, teruskan nilai berikut dalam permintaan Anda:

  • Dengan autentikasi aplikasi, tentukan cakupan otorisasi chat.bot. Dengan autentikasi pengguna, tentukan cakupan otorisasi chat.messages.create.
  • Panggil metode create di resource Message.

Mengirim pesan teks dengan autentikasi aplikasi

Berikut cara mengirim pesan teks dengan autentikasi aplikasi:

Python

  1. Di direktori kerja, buat file bernama chat_create_text_message_app.py.
  2. Sertakan kode berikut di chat_create_text_message_app.py:

    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)
    
  3. Dalam kode, ganti SPACE dengan nama ruang, yang dapat Anda peroleh dari metode spaces.list() di Chat API, atau dari URL ruang.

  4. Di direktori kerja Anda, buat dan jalankan contoh:

    python3 chat_create_text_message_app.py
    

Chat API menampilkan instance Message yang menjelaskan pesan yang dikirim.

Mengirim pesan teks dengan autentikasi pengguna

Berikut cara mengirim pesan teks dengan autentikasi pengguna:

Python

  1. Di direktori kerja, buat file bernama chat_create_text_message_user.py.
  2. Sertakan kode berikut di 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. Dalam kode, ganti SPACE dengan nama ruang, yang dapat Anda peroleh dari metode spaces.list() di Chat API, atau dari URL ruang.

  4. Di direktori kerja Anda, buat dan jalankan contoh:

    python3 chat_create_text_message_user.py
    

Chat API menampilkan instance Message yang menjelaskan pesan yang dikirim.

Kirim pesan kartu

Bagian ini menjelaskan cara mengirim pesan kartu dalam dua cara berikut:

  • Mengirim pesan kartu secara real time dengan merespons interaksi pengguna.
  • Kirim pesan kartu dengan memanggil Google Chat API secara asinkron.


Desain dan pratinjau kartu dengan Pembuat Kartu.

Buka Pembuat Kartu

Mengirim pesan kartu secara real time

Aplikasi Chat dapat membuat pesan kartu untuk merespons interaksi pengguna, seperti saat pengguna mengirim pesan ke aplikasi Chat atau menambahkan aplikasi Chat ke ruang. Untuk mempelajari lebih lanjut cara merespons interaksi pengguna, lihat Menerima dan merespons peristiwa interaksi aplikasi Chat.

Dalam contoh ini, pengguna mengirim pesan ke aplikasi Chat dan aplikasi Chat merespons dengan mengirim pesan kartu yang menampilkan nama dan gambar avatar pengguna:

Aplikasi Chat merespons dengan kartu yang menampilkan nama tampilan dan gambar
avatar pengirim.

Node.js

node/avatar-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

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],
      }
    }],
  };
}

Mengirim pesan kartu secara asinkron

Untuk mengirim pesan kartu, teruskan hal berikut dalam permintaan Anda:

  • Dengan autentikasi aplikasi, tentukan cakupan otorisasi chat.bot. Anda tidak dapat mengirim pesan kartu dengan autentikasi pengguna.
  • Panggil metode create di resource Message.

Berikut adalah contoh pesan kartu:

Pesan kartu yang dikirim dengan Chat API.

Berikut cara mengirim pesan kartu dengan autentikasi aplikasi:

Python

  1. Di direktori kerja, buat file bernama chat_create_card_message.py.
  2. Sertakan kode berikut di chat_create_card_message.py:

    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)
    
  3. Dalam kode, ganti SPACE dengan nama ruang, yang dapat Anda peroleh dari metode spaces.list di Chat API, atau dari URL ruang.

  4. Di direktori kerja Anda, buat dan jalankan contoh:

    python3 chat_create_card_message.py
    

Memulai atau membalas rangkaian pesan

Untuk memulai rangkaian pesan, kirim pesan dan biarkan thread.name kosong; Google Chat akan mengisinya saat membuat rangkaian pesan. Secara opsional, untuk menyesuaikan nama thread, tentukan kolom thread.threadKey.

Untuk membalas rangkaian pesan, kirim pesan yang menentukan kolom threadKey atau name rangkaian pesan. Jika rangkaian pesan dibuat oleh pengguna atau aplikasi Chat lain, Anda harus menggunakan kolom thread.name.

Jika tidak ditemukan thread yang cocok, Anda dapat menentukan apakah pesan harus memulai thread baru atau gagal diposting dengan menetapkan kolom messageReplyOption.

Berikut cara memulai atau membalas rangkaian pesan dengan kolom threadKey yang ditentukan sebagai nameOfThread:

Python

  1. Di direktori kerja, buat file bernama chat_create_message_thread.py.
  2. Sertakan kode berikut di chat_create_message_thread.py:

    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)
    
  3. Dalam kode, ganti SPACE dengan nama ruang, yang dapat Anda peroleh dari metode spaces.list di Chat API, atau dari URL ruang.

  4. Di direktori kerja Anda, buat dan jalankan contoh:

    python3 chat_create_message_thread.py
    

Chat API menampilkan instance Message yang menjelaskan pesan yang dikirim.

Memberi nama pesan

Bagian ini menjelaskan cara memberi nama pesan dengan menetapkan ID kustom untuk pesan tersebut. Anda dapat menggunakan ID kustom untuk mendapatkan, memperbarui, atau menghapus pesan. ID kustom memungkinkan Anda menentukan pesan tanpa perlu menyimpan ID yang ditetapkan sistem dari nama resource pesan (diwakili dalam kolom name). Nama resource dibuat dalam isi respons saat Anda membuat pesan.

Misalnya, untuk mengambil pesan menggunakan metode get(), gunakan nama resource untuk menentukan pesan yang akan diambil. Nama resource diformat sebagai spaces/{space}/messages/{message}, dengan {message} mewakili ID yang ditetapkan oleh sistem. Jika memberi nama pesan tersebut, Anda dapat mengganti nilai {message} dengan ID kustom.

Untuk menamai pesan, tentukan ID kustom di kolom messageId saat membuat pesan. Kolom messageId menetapkan nilai untuk kolom clientAssignedMessageId dari resource Message.

Anda hanya dapat memberi nama pesan saat membuat pesan. Anda tidak dapat memberi nama atau mengubah ID kustom untuk pesan yang ada. ID kustom harus memenuhi persyaratan berikut:

  • Diawali dengan client-. Misalnya, client-custom-name adalah ID kustom yang valid, sedangkan custom-name tidak.
  • Berisi hingga 63 karakter dan hanya huruf kecil, angka, serta tanda hubung.
  • Bersifat unik dalam ruang. Aplikasi Chat tidak dapat menggunakan ID kustom yang sama untuk pesan yang berbeda.

Berikut cara mengirim pesan dengan ID kustom:

Python

  1. Di direktori kerja, buat file bernama chat_create_named_message.py.
  2. Sertakan kode berikut di chat_create_named_message.py:

    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)
    
  3. Dalam kode, ganti kode berikut:

    • SPACE: ID untuk ruang tempat Anda ingin memposting pesan, yang dapat diperoleh dari metode spaces.list di Chat API, atau dari URL ruang.
    • NAME: Nama kustom untuk pesan.
  4. Di direktori kerja Anda, buat dan jalankan contoh:

    python3 chat_create_named_message.py
    

Chat API menampilkan instance Message.

Mengirim pesan secara pribadi

Aplikasi chat dapat mengirim pesan teks dan kartu secara pribadi sehingga pesan hanya terlihat oleh satu pengguna dalam ruang. Untuk mengirim pesan secara pribadi, tentukan kolom privateMessageViewer dalam pesan. Hanya aplikasi Chat yang dapat mengirim pesan pribadi. Untuk mengirim pesan pribadi secara asinkron, Anda harus menggunakan autentikasi aplikasi.

Untuk mengetahui detailnya, lihat Mengirim pesan pribadi kepada pengguna Google Chat.

Memecahkan masalah

Saat aplikasi atau kartu Google Chat menampilkan error, antarmuka Chat akan menampilkan pesan yang menyatakan "Terjadi masalah". atau "Tidak dapat memproses permintaan Anda". Terkadang UI Chat tidak menampilkan pesan error apa pun, tetapi aplikasi atau kartu Chat memberikan hasil yang tidak diharapkan; misalnya, pesan kartu mungkin tidak muncul.

Meskipun pesan error mungkin tidak ditampilkan di UI Chat, pesan error deskriptif dan data log tersedia untuk membantu Anda memperbaiki error saat logging error untuk aplikasi Chat diaktifkan. Untuk mendapatkan bantuan dalam melihat, men-debug, dan memperbaiki error, lihat Memecahkan masalah dan memperbaiki error Google Chat.