Panduan ini menjelaskan berbagai cara aplikasi Google Chat dapat mengirim pesan:
- Kirim pesan teks dan kartu secara real time dengan merespons pengguna interaksi.
- Kirim pesan teks dan kartu secara asinkron dengan memanggil metode
create
di resourceMessage
. - Memulai atau membalas rangkaian pesan.
- Mengirim dan memberi nama pesan.
Tujuan
Referensi Message
mewakili
teks
atau
kartu
untuk mengirim pesan 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.
Ukuran pesan maksimum (termasuk teks atau kartu apa pun) adalah 32.000 byte. Jika pesan melebihi ukuran ini, aplikasi Chat Anda dapat mengirim beberapa pesan.
Daripada memanggil metode create
pada resource Message
Google Chat API untuk mengirim pesan teks atau kartu secara asinkron,
Aplikasi Google Chat juga dapat membuat pesan untuk merespons interaksi pengguna di
secara real-time. Respons terhadap interaksi pengguna
tidak memerlukan otentikasi dan
mendukung jenis pesan lain, termasuk dialog interaktif dan link
pratinjau. Untuk mengetahui detailnya, lihat
Menerima dan merespons interaksi dengan aplikasi Google Chat.
Prasyarat
Node.js
- Aplikasi Google Chat. Untuk membuat aplikasi Chat menggunakan layanan HTTP, selesaikan panduan memulai.
- Otorisasi dikonfigurasi untuk aplikasi Chat agar dapat mengirim
dan asinkron. Tidak ada konfigurasi otorisasi
yang diperlukan untuk mengirim
membuat pesan secara real time.
- Mengirim
pesan teks
mendukung kedua metode otorisasi berikut:
- Autentikasi pengguna
dengan otorisasi
chat.messages.create
atauchat.messages
ruang lingkup proyek. - Autentikasi aplikasi
dengan cakupan otorisasi
chat.bot
.
- Autentikasi pengguna
dengan otorisasi
- Mengirim
pesan kartu
memerlukan
autentikasi aplikasi
dengan cakupan otorisasi
chat.bot
.
- Mengirim
pesan teks
mendukung kedua metode otorisasi berikut:
Python
- Aplikasi Google Chat. Untuk membuat aplikasi Chat menggunakan layanan HTTP, selesaikan panduan memulai.
- Otorisasi dikonfigurasi untuk aplikasi Chat agar dapat mengirim
dan asinkron. Tidak ada konfigurasi otorisasi
yang diperlukan untuk mengirim
membuat pesan secara real time.
- Mengirim
pesan teks
mendukung kedua metode otorisasi berikut:
- Autentikasi pengguna
dengan otorisasi
chat.messages.create
atauchat.messages
ruang lingkup proyek. - Autentikasi aplikasi
dengan cakupan otorisasi
chat.bot
.
- Autentikasi pengguna
dengan otorisasi
- Mengirim
pesan kartu
memerlukan
autentikasi aplikasi
dengan cakupan otorisasi
chat.bot
.
- Mengirim
pesan teks
mendukung kedua metode otorisasi berikut:
Apps Script
- Aplikasi Google Chat. Untuk membuat aplikasi Chat di Apps Script, selesaikan panduan memulai.
- Otorisasi dikonfigurasi untuk aplikasi Chat agar dapat mengirim
dan asinkron. Tidak ada konfigurasi otorisasi
yang diperlukan untuk mengirim
mengirim pesan secara real time.
- Mengirim
pesan teks
mendukung kedua metode otorisasi berikut:
- Autentikasi pengguna
dengan otorisasi
chat.messages.create
atauchat.messages
ruang lingkup proyek. - Autentikasi aplikasi
dengan cakupan otorisasi
chat.bot
.
- Autentikasi pengguna
dengan otorisasi
- Mengirim
pesan kartu
memerlukan
autentikasi aplikasi
dengan cakupan otorisasi
chat.bot
.
- Mengirim
pesan teks
mendukung kedua metode otorisasi berikut:
Kirim SMS
Bagian ini menjelaskan cara mengirim pesan teks dengan dua cara berikut:
- Kirim pesan teks secara real time dengan menanggapi interaksi pengguna.
- Kirim pesan teks dengan memanggil Google Chat API secara asinkron.
Kirim SMS secara real time
Dalam contoh ini, aplikasi Chat Anda membuat dan mengirim teks setiap kali ditambahkan ke ruang. Untuk mempelajari tentang praktik baik untuk proses orientasi pengguna, lihat Mulai buat orang dan ruang dengan orientasi yang bermanfaat.
Untuk mengirim pesan teks saat pengguna menambahkan aplikasi Chat Anda
ke ruang, aplikasi Chat Anda
merespons ADDED_TO_SPACE
peristiwa interaksi. Untuk menanggapi
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 ini menampilkan pesan teks berikut:
Mengirim pesan teks secara asinkron
Bagian berikut menjelaskan cara mengirim pesan teks secara asinkron dengan autentikasi aplikasi dan autentikasi pengguna.
Untuk mengirim SMS, teruskan hal berikut dalam permintaan Anda:
- Dengan autentikasi aplikasi, tentukan cakupan otorisasi
chat.bot
. Dengan autentikasi pengguna, tentukan cakupan otorisasichat.messages.create
. - Panggil
Metode
create
di ResourceMessage
.
Mengirim pesan teks dengan autentikasi aplikasi
Berikut adalah cara untuk mengirim pesan teks dengan autentikasi aplikasi:
Python
- Di direktori kerja, buat file bernama
chat_create_text_message_app.py
. 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)
Dalam kode, ganti
SPACE
dengan nama ruang, yang yang dapat diperoleh dari Metodespaces.list()
di Chat API, atau dari URL ruang.Dalam direktori kerja, build dan jalankan contoh:
python3 chat_create_text_message_app.py
Chat API menampilkan instance
Message
yang merinci
pesan yang dikirim.
Mengirim pesan teks dengan autentikasi pengguna
Berikut adalah cara untuk mengirim pesan teks dengan autentikasi pengguna:
Python
- Di direktori kerja, buat file bernama
chat_create_text_message_user.py
. 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 message. print(result) if __name__ == '__main__': main()
Dalam kode, ganti
SPACE
dengan nama ruang, yang yang dapat diperoleh dari Metodespaces.list()
di Chat API, atau dari URL ruang.Dalam direktori kerja, build dan jalankan contoh:
python3 chat_create_text_message_user.py
Chat API menampilkan instance
Message
yang merinci
pesan yang dikirim.
Kirim pesan kartu
Bagian ini menjelaskan cara mengirim pesan kartu dalam dua cara berikut:
- Kirim pesan kartu secara real time dengan merespons interaksi pengguna.
- Kirim pesan kartu dengan memanggil Google Chat API secara asinkron.
Kirim pesan kartu secara real time
Aplikasi Chat dapat membuat pesan kartu untuk merespons pengguna interaksi, seperti saat pengguna mengirim sebuah aplikasi Chat ke aplikasi Chat atau menambahkan aplikasi Chat ke ruang. Untuk mempelajari lebih lanjut tentang merespons interaksi pengguna, lihat Menerima dan menanggapi Interaksi aplikasi Chat peristiwa.
Dalam contoh ini, pengguna mengirim pesan ke aplikasi Chat dan aplikasi Chat merespons dengan mengirimkan pesan kartu yang menampilkan nama dan gambar avatar pengguna:
Node.js
Python
Apps Script
Contoh ini mengirimkan pesan kartu dengan mengembalikan JSON kartu. Anda juga dapat menggunakan Layanan kartu Apps Script.
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 bisa mengirim pesan ke kartu dengan otentikasi pengguna. - Panggil
Metode
create
di ResourceMessage
.
Berikut adalah contoh pesan kartu:
Berikut cara mengirimkan pesan kartu dengan autentikasi aplikasi:
Python
- Di direktori kerja, buat file bernama
chat_create_card_message.py
. 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)
Dalam kode, ganti
SPACE
dengan nama ruang, yang yang dapat diperoleh dari Metodespaces.list
di Chat API, atau dari URL ruang.Dalam direktori kerja, build dan jalankan contoh:
python3 chat_create_card_message.py
Memulai atau membalas rangkaian pesan
Untuk memulai rangkaian pesan, kirim pesan dan keluar dari rangkaian pesan
thread.name
kosong; Google Chat akan mengisinya saat membuat thread. Secara opsional, untuk
menyesuaikan nama thread, menentukan
thread.threadKey
kolom tersebut.
Untuk membalas rangkaian pesan, kirim pesan yang menentukan
Kolom threadKey
atau name
. Jika rangkaian pesan dibuat oleh seseorang atau orang lain
Aplikasi Chat, Anda harus menggunakan kolom thread.name
.
Jika tidak ditemukan thread yang cocok, Anda dapat menentukan
apakah pesan harus memulai rangkaian pesan baru atau gagal memposting dengan
messageReplyOption
kolom tersebut.
Jika messageReplyOption
disetel, Anda juga harus menetapkan thread.name
atau thread.threadKey
.
Berikut cara memulai atau membalas rangkaian pesan dengan kolom threadKey
yang ditentukan sebagai
nameOfThread
:
Python
- Di direktori kerja, buat file bernama
chat_create_message_thread.py
. 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)
Dalam kode, ganti
SPACE
dengan nama ruang, yang yang dapat diperoleh dari Metodespaces.list
di Chat API, atau dari URL ruang.Dalam direktori kerja, build dan jalankan contoh:
python3 chat_create_message_thread.py
Chat API menampilkan instance
Message
yang merinci
pesan yang dikirim.
Memberi nama pesan
Bagian ini menjelaskan cara memberi nama pesan dengan menyetel ID kustom untuk
untuk membuat pesan email baru. Anda dapat menggunakan ID kustom untuk mendapatkan, memperbarui, atau menghapus pesan. ID Kustom
memungkinkan Anda untuk menentukan pesan tanpa
perlu menyimpan ID yang ditetapkan sistem dari
nama resource pesan (diwakili dalam kolom name
). Sumber daya
nama akan dibuat dalam
isi respons
saat Anda membuat pesan.
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 oleh sistem. Jika telah menamai pesan, Anda dapat mengganti
nilai {message}
dengan ID kustom.
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 hingga 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.
Berikut adalah cara mengirim pesan dengan ID kustom:
Python
- Di direktori kerja, buat file bernama
chat_create_named_message.py
. 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)
Dalam kode, ganti kode berikut:
SPACE
: ID untuk ruang tempat Anda ingin kirimkan pesan, yang dapat diperoleh dari Metodespaces.list
di Chat API, atau dari URL ruang.NAME
: Nama kustom untuk pesan.
Dalam direktori kerja, build dan jalankan contoh:
python3 chat_create_named_message.py
Chat API menampilkan instance
Message
Menambahkan widget interaktif di bagian bawah pesan
Anda juga dapat menambahkan pesan dengan widget aksesori. Widget aksesori ditampilkan setelah teks atau kartu dalam pesan. Anda dapat menggunakan widget untuk meminta pengguna berinteraksi dengan pesan Anda dalam berbagai 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[]
dalam pesan dan tentukan satu atau beberapa
AccessoryWidgets
yang ingin Anda sertakan. Pesan harus dapat dilihat oleh semua orang dalam ruang
(Anda tidak dapat menambahkan widget aksesori ke pesan pribadi).
Gambar berikut menunjukkan aplikasi Chat yang menambahkan pesan teks dengan widget aksesori agar pengguna dapat menilai pengalaman mereka dengan aplikasi Chat.
Contoh kode berikut menampilkan JSON untuk pesan ini. Saat pengguna mengklik
salah satu tombol, interaksi tersebut akan memicu fungsi yang sesuai (seperti
doUpvote
) yang memproses rating.
"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 teks dan kartu secara pribadi sehingga
pesan hanya dapat dilihat oleh satu pengguna dalam ruang. Untuk mengirim pesan secara pribadi,
Anda menentukan kolom privateMessageViewer
dalam pesan. Hanya
Aplikasi chat dapat mengirim pesan pribadi. Untuk mengirim pesan pribadi
secara asinkron, Anda harus menggunakan autentikasi aplikasi.
Untuk mengetahui detailnya, lihat Mengirim pesan pribadi ke Google Chat pengguna.
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
- 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.