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.
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
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
- Sebuah Business atau Enterprise Akun Google Workspace yang memiliki akses ke Google Chat.
- 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
- Menyiapkan lingkungan Anda:
- Buat project Google Cloud.
- Konfigurasi layar izin OAuth.
- Aktifkan dan konfigurasikan Google Chat API dengan nama, ikon, dan deskripsi untuk aplikasi Chat Anda.
- Buat kredensial akses berdasarkan cara Anda ingin melakukan autentikasi di Google Chat API
permintaan:
- Untuk melakukan autentikasi sebagai pengguna Chat,
buat client ID OAuth
kredensial, lalu simpan kredensial sebagai file JSON yang bernama
client_secrets.json
ke direktori lokal Anda. - Untuk melakukan autentikasi sebagai aplikasi Chat,
buat akun layanan
kredensial, lalu simpan kredensial sebagai file JSON yang bernama
credentials.json
.
- Untuk melakukan autentikasi sebagai pengguna Chat,
buat client ID OAuth
kredensial, lalu simpan kredensial sebagai file JSON yang bernama
- Pilih cakupan otorisasi berdasarkan apakah Anda ingin melakukan autentikasi sebagai pengguna atau Aplikasi Chat.
- Ruang Google Chat tempat pengguna yang diautentikasi atau memanggil aplikasi Chat adalah anggotanya. Untuk mengotentikasi sebagai aplikasi Chat, tambahkan Chat ke ruang.
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.
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 atributtext
kolom tersebut.
Secara opsional, Anda dapat menyertakan hal berikut:
- Kolom
messageId
, yang memungkinkan Anda memberi nama pesan yang akan digunakan dalam permintaan API lainnya. - Kolom
thread.threadKey
danmessageReplyOption
untuk memulai atau membalas rangkaian pesan. Jika ruang tidak menggunakan rangkaian pesan, kolom ini akan diabaikan.
Untuk mengirim pesan teks atas nama pengguna, lakukan langkah-langkah berikut:
Python
- Di direktori kerja, buat file bernama
chat_create_message_user.py
. 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 dariname
kolom tersebut. Anda bisa mendapatkan ID dengan memanggil Metodespaces.list()
atau dari URL ruang.Dalam direktori kerja, build dan jalankan contoh:
python3 chat_create_message_user.py
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.
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:
- Kolom
accessoryWidgets
yang akan disertakan tombol interaktif di bagian bawah pesan. - Kolom
privateMessageViewer
untuk mengirim pesan secara pribadi ke pengguna tertentu. - Kolom
messageId
, yang memungkinkan Anda memberi nama pesan yang akan digunakan dalam permintaan API lainnya. - Kolom
thread.threadKey
danmessageReplyOption
untuk memulai atau membalas rangkaian pesan. Jika ruang tidak menggunakan rangkaian pesan, kolom ini akan diabaikan.
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
- Di direktori kerja, buat file bernama
chat_create_message_app.py
. 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 dariname
kolom tersebut. Anda bisa mendapatkan ID dengan memanggil Metodespaces.list()
atau dari URL ruang.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.](https://developers.google.cn/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=9&hl=id)
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 menentukanthreadKey
yang Anda buat. Jika tidak, Anda harus menggunakanname
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, tetapicustom-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.
Topik terkait
- Menggunakan Card Builder untuk mendesain dan melihat pratinjau pesan kartu JSON untuk aplikasi Chat.
- Memformat pesan.
- Mendapatkan detail tentang pesan.
- Mencantumkan pesan dalam ruang.
- Memperbarui pesan.
- Menghapus pesan.
- Mengidentifikasi pengguna dalam pesan Google Chat.
- Kirim pesan ke Google Chat dengan webhook masuk.