Mengirim pesan menggunakan Google Chat API

Panduan ini menjelaskan cara memanggil API Google Chat messages.create() metode untuk melakukan salah satu tindakan berikut:

  • Kirim pesan yang berisi teks, kartu, dan widget interaktif.
  • Mengirim pesan secara pribadi kepada pengguna Chat tertentu.
  • Memulai atau membalas rangkaian pesan.
  • Beri nama pesan sehingga Anda dapat menentukannya di Chat API lain permintaan.

Selain memanggil metode messages.create(), aplikasi Chat dapat membuat dan mengirim pesan untuk membalas interaksi pengguna, seperti memposting pesan selamat datang setelah pengguna menambahkan aplikasi Chat ke spasi. Saat merespons interaksi, aplikasi Chat dapat menggunakan jenis fitur pesan, termasuk dialog interaktif dan pratinjau link antarmuka. Untuk membalas pengguna, aplikasi Chat akan kembali pesan secara sinkron, tanpa memanggil Chat API. Untuk mempelajari tentang mengirim pesan untuk merespons interaksi, lihat Menerima dan merespons interaksi dengan aplikasi Google Chat.

Cara Chat menampilkan dan mengatribusikan pesan yang dibuat dengan Chat API

Anda dapat memanggil metode messages.create() menggunakan autentikasi aplikasi dan autentikasi pengguna. Chat mengatribusikan pengirim pesan secara berbeda tergantung pada jenis otentikasi yang Anda gunakan.

Saat Anda melakukan autentikasi sebagai aplikasi Chat, aplikasi Chat mengirimkan pesan.

Memanggil metode messages.create() dengan autentikasi aplikasi.
Gambar 1: Dengan autentikasi aplikasi, aplikasi Chat mengirim menulis pesan. Perlu diketahui bahwa pengirim bukan orang, Chat menampilkan App di samping namanya.

Saat Anda melakukan autentikasi sebagai pengguna, aplikasi Chat akan mengirim pesan atas nama pengguna. Chat juga mengaitkan Aplikasi Chat ke pesan dengan menampilkan namanya

Memanggil metode messages.create() dengan autentikasi pengguna.
Gambar 2: Dengan autentikasi pengguna, pengguna dapat mengirim pesan, dan Chat menampilkan Nama aplikasi Chat di samping nama pengguna.

Jenis otentikasi juga menentukan fitur dan antarmuka pesan mana yang dapat Anda sertakan dalam pesan tersebut. Dengan otentikasi aplikasi, Aplikasi chat dapat mengirim pesan yang berisi teks kaya, antarmuka berbasis kartu, dan {i>widget<i} interaktif. Karena pengguna Chat hanya dapat mengirim teks dalam pesan mereka, Anda dapat hanya menyertakan teks saat membuat pesan menggunakan otentikasi pengguna. Untuk mempelajari fitur pesan lebih lanjut yang tersedia untuk Chat API, lihat Ringkasan pesan Google Chat.

Panduan ini menjelaskan cara menggunakan salah satu jenis autentikasi untuk mengirim pesan dengan Chat API.

Prasyarat

Python

  • Python 3.6 atau yang lebih baru
  • Alat pengelolaan paket pip
  • Library klien Google terbaru. Untuk menginstal atau memperbaruinya, jalankan perintah berikut di antarmuka command line Anda: 
    pip3 install --upgrade google-api-python-client google-auth-oauthlib

Mengirim pesan teks atas nama pengguna

Bagian ini menjelaskan cara mengirim pesan atas nama pengguna menggunakan autentikasi pengguna. Dengan autentikasi pengguna, isi pesan hanya dapat berisi teks dan wajib menghapus fitur pesan yang hanya tersedia untuk Aplikasi chat, termasuk antarmuka kartu dan widget interaktif.

Pesan dikirim dengan autentikasi pengguna
Gambar 3. Aplikasi Chat mengirimkan pesan teks pada nama pengguna.

Untuk memanggil messages.create() menggunakan autentikasi pengguna, Anda harus menentukan kolom berikut dalam permintaan:

  • Cakupan otorisasi yang mendukung otentikasi pengguna untuk metode ini. Contoh berikut menggunakan cakupan chat.messages.create.
  • Resource Space tempat tempat Anda ingin memposting pesan. Pengguna terautentikasi haruslah anggota spasi.
  • Message resource yang akan dibuat. Untuk mendefinisikan isi pesan, Anda harus menyertakan atribut text kolom tersebut.

Secara opsional, Anda dapat menyertakan hal berikut:

Untuk mengirim pesan teks atas nama pengguna, lakukan langkah-langkah berikut:

Python

  1. Di direktori kerja, buat file bernama chat_create_message_user.py.

  2. Sertakan kode berikut di chat_create_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',

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

    Ganti SPACE dengan ID dari name kolom tersebut. Anda bisa mendapatkan ID dengan memanggil Metode spaces.list() atau dari URL ruang.

  3. Dalam direktori kerja, build dan jalankan contoh:

    python3 chat_create_message_user.py

  4. Jika diminta dengan URL, buka URL untuk memberi otorisasi Aplikasi Chat berdasarkan cakupan yang Anda gunakan dalam permintaan.

Aplikasi Chat membuat pesan, dan autentikasi pengguna memposting pesan dalam ruang. Di antarmuka command line, Chat API menampilkan instance Resource Message.

Mengirim pesan sebagai aplikasi Chat

Bagian ini menjelaskan cara mengirim pesan yang berisi teks, kartu, dan widget aksesori interaktif menggunakan autentikasi aplikasi.

Pesan dikirim dengan autentikasi aplikasi
Gambar 4. Aplikasi Chat mengirim pesan dengan teks, kartu, dan tombol aksesori.

Untuk memanggil messages.create() menggunakan autentikasi aplikasi, Anda harus menentukan kolom berikut dalam permintaan:

  • Cakupan otorisasi chat.bot.
  • Resource Space tempat tempat Anda ingin memposting pesan. Aplikasi Chat harus anggota ruang.
  • Message resource yang akan dibuat. Untuk menentukan isi pesan, Anda dapat menyertakan teks kaya (text), satu atau beberapa antarmuka kartu (cardsV2), atau keduanya.

Secara opsional, Anda dapat menyertakan hal berikut:

Ukuran pesan maksimum (termasuk teks atau kartu apa pun) adalah 32.000 byte. Untuk mengirim pesan yang melebihi ukuran ini, aplikasi Chat Anda harus mengirim beberapa pesan.

Untuk mengirim pesan yang diposting sebagai aplikasi Chat yang berisi teks, kartu, dan tombol yang dapat diklik di bagian bawah pesan, lakukan langkah-langkah berikut:

Python

  1. Di direktori kerja, buat file bernama chat_create_message_app.py.

  2. Sertakan kode berikut di chat_create_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)

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

    Ganti SPACE dengan ID dari name kolom tersebut. Anda bisa mendapatkan ID dengan memanggil Metode spaces.list() atau dari URL ruang.

  3. Dalam direktori kerja, build dan jalankan contoh:

    python3 chat_create_message_app.py

Aplikasi Chat membuat dan memposting pesan di spasi. Di antarmuka command line, Chat API menampilkan instance dari Resource Message.

Menambahkan widget interaktif di bagian bawah pesan

Dalam contoh kode dari bagian sebelumnya, Pesan aplikasi Chat menampilkan tombol yang dapat diklik di bagian bawah pesan, yang dikenal sebagai widget aksesori. Widget aksesori akan muncul setelah teks atau kartu dalam pesan. Anda dapat menggunakan widget ini untuk berinteraksi dengan pesan Anda dalam banyak cara, termasuk hal berikut:

  • Memberi rating akurasi atau kepuasan pesan.
  • Laporkan masalah terkait pesan atau aplikasi Chat.
  • Buka link ke konten terkait, seperti dokumentasi.
  • Menutup atau menunda pesan serupa dari aplikasi Chat selama jangka waktu tertentu.

Untuk menambahkan widget aksesori, sertakan accessoryWidgets[] di isi permintaan Anda dan tentukan satu atau beberapa widget yang diinginkan untuk disertakan.

Gambar berikut menunjukkan aplikasi Chat yang menambahkan pesan teks dengan widget aksesori agar pengguna dapat menilai pengalaman mereka dengan aplikasi Chat.

Widget aksesori.
Gambar 5: Pesan aplikasi Chat dengan widget teks dan aksesori.

Berikut ini adalah isi permintaan yang membuat pesan teks dengan dua tombol aksesori. Saat pengguna mengeklik tombol, atribut (seperti doUpvote) memproses interaksi:


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

Mengirim pesan secara pribadi

Aplikasi Chat dapat mengirim pesan secara pribadi sehingga pesan hanya dapat dilihat oleh pengguna tertentu dalam ruang. Ketika seorang Aplikasi Chat mengirimkan pesan pribadi, yaitu pesan menampilkan label yang memberi tahu pengguna bahwa pesan tersebut hanya dapat dilihat oleh mereka.

Untuk mengirim pesan secara pribadi menggunakan Chat API, tentukan atribut privateMessageViewer di isi permintaan Anda. Untuk menentukan pengguna, Anda menetapkan nilai ke resource User yang mewakili pengguna Chat. Anda juga dapat menggunakan Kolom name halaman User, seperti yang ditunjukkan dalam contoh berikut:

{
    "text": "Hello private world!",
    "privateMessageViewer": {
      "name": "users/USER_ID"
    }
}

Ganti USER_ID dengan ID unik untuk pengguna tersebut, seperti 12345678987654321 atau hao@cymbalgroup.com. Untuk informasi selengkapnya tentang menentukan pengguna, lihat Mengidentifikasi dan menentukan pengguna Google Chat.

Untuk mengirim pesan secara pribadi, Anda harus menghapus hal berikut dalam permintaan:

Memulai atau membalas dalam rangkaian pesan

Untuk ruang yang menggunakan thread, Anda dapat menentukan apakah pesan baru memulai rangkaian pesan, atau membalas ke rangkaian pesan yang sudah ada.

Secara default, pesan yang Anda buat menggunakan Chat API akan memulai . Untuk membantu Anda mengidentifikasi rangkaian pesan dan membalasnya nanti, Anda dapat menentukan kunci thread dalam permintaan Anda:

  • Dalam isi permintaan Anda, tentukan thread.threadKey kolom tersebut.
  • Menentukan parameter kueri messageReplyOption untuk menentukan apa yang akan terjadi jika kunci tersebut sudah ada.

Untuk membuat pesan yang membalas rangkaian pesan yang ada:

  • Dalam isi permintaan Anda, sertakan kolom thread. Jika diatur, Anda dapat menentukan threadKey yang Anda buat. Jika tidak, Anda harus menggunakan name dari utas.
  • Tentukan parameter kueri messageReplyOption.

JSON berikut menunjukkan contoh isi permintaan untuk pesan teks yang memulai atau membalas rangkaian pesan dengan kunci helloWorldThread:

   {
     'thread': {
      'threadKey': 'helloWorldThread',
     },
     'text': '👋 🌎Hello world!'
   }

Memberi nama pesan

Untuk mengambil atau menetapkan pesan dalam panggilan API mendatang, Anda dapat memberi nama pesan dengan menyetel kolom messageId dalam permintaan messages.create() Anda. Memberi nama pesan memungkinkan Anda menentukan pesan tanpa perlu menyimpan ID yang ditetapkan sistem dari nama resource pesan (diwakili dalam name ).

Misalnya, untuk mengambil pesan menggunakan metode get(), Anda menggunakan nama resource untuk menetapkan pesan yang akan diambil. Nama resource-nya adalah diformat sebagai spaces/{space}/messages/{message}, dengan {message} mewakili ID yang ditetapkan sistem atau nama kustom yang Anda tetapkan saat membuat untuk membuat pesan email baru.

Untuk memberi nama pesan, tentukan ID kustom di messageId saat Anda membuat pesan. Kolom messageId menetapkan nilai untuk clientAssignedMessageId pada kolom 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 persyaratan:

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

Memecahkan masalah

Saat aplikasi Google Chat atau kartu menampilkan error, Antarmuka Chat menampilkan pesan yang bertuliskan "Terjadi masalah". atau "Tidak dapat memproses permintaan Anda". Terkadang UI Chat tidak menampilkan pesan error apa pun, tetapi aplikasi Chat atau memberikan hasil yang tidak diharapkan; misalnya, pesan kartu mungkin tidak akan 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 bantuan melihat, men-debug, dan memperbaiki error, melihat Memecahkan masalah dan memperbaiki error Google Chat.