Panduan ini menjelaskan cara menerima dan membaca informasi yang dimasukkan pengguna dalam pesan kartu dan dialog. Pengguna dapat memasukkan data yang diterima, dibaca, dan direspons oleh aplikasi Chat. Widget yang memungkinkan pengguna memasukkan informasi mencakup hal berikut:
TextInput
untuk entri teks bentuk bebas yang juga mendukung saran.SelectionInput
untuk item dan menu daftar, seperti kotak centang, tombol pilihan, dan menu drop-down.DateTimePicker
untuk entri tanggal dan waktu.
Gunakan Card Builder untuk mendesain dan melihat pratinjau pesan kartu JSON untuk aplikasi Chat:
Buka Pembuat KartuMenerima input data dari pengguna memungkinkan aplikasi Chat melakukan hal-hal berikut:
- Perbarui kasus layanan pelanggan.
- Membuat perintah kerja.
- Melakukan autentikasi dengan layanan web.
Cara kerja penerimaan data
Aplikasi Chat menyajikan informasi kepada pengguna sebagai
dialog atau pesan kartu. Dalam contoh ini, dialog meminta pengguna untuk memasukkan
informasi tentang kontak menggunakan widget
TextInput
dan
SelectionInput
:
Setelah selesai, aplikasi Chat akan menerima data yang dimasukkan pengguna dalam dialog dalam format JSON dan peristiwa interaksi dengan:
EventType
adalahCARD_CLICKED
.DialogEventType
adalahSUBMIT_DIALOG
(hanya untuk dialog).
Untuk mendapatkan data tentang hal yang dimasukkan pengguna, gunakan kolom Event.common.formInputs
di payload peristiwa. Kolom formInputs
adalah peta dengan kunci yang ditetapkan
ID string ke setiap widget dan nilai mewakili input pengguna untuk
setiap widget. Objek yang berbeda mewakili tipe data input yang berbeda. Misalnya,
Event.common.formInputs.stringInputs
mewakili input string.
Aplikasi Anda dapat mengakses nilai pertama yang dimasukkan pengguna di
event.common.formInputs.NAME.stringInputs.value[0]
,
dengan NAME
sebagai kolom name
dari
widget TextInput
.
Menerima data dari kartu
Saat pengguna memasukkan data dalam pesan kartu, aplikasi Chat Anda akan menerima peristiwa interaksi aplikasi Chat, seperti contoh berikut:
JSON
{
"type": enum (EventType),
"eventTime": string,
"threadKey": string,
"message": {
object (Message)
},
"user": {
object (User)
},
"space": {
object (Space)
},
"action": {
object (FormAction)
},
"configCompleteRedirectUrl": string,
"common": {
// Represents user data entered in a card.
"formInputs": {
// Represents user data entered for a specific field in a card.
"NAME": {
// Represents string data entered in a card, like text input fields
// and check boxes.
"stringInputs": {
// An array of strings entered by the user in a card.
"value": [
string
]
}
}
},
"parameters": {
string: string,
...
},
"invokedFunction": string
}
}
Menerima data dari dialog
Saat pengguna mengirimkan data dalam dialog, aplikasi Chat Anda akan menerima peristiwa interaksi aplikasi Chat lainnya, seperti contoh berikut:
JSON
{
"type": enum (EventType),
"eventTime": string,
"threadKey": string,
"message": {
object (Message)
},
"user": {
object (User)
},
"space": {
object (Space)
},
"action": {
object (FormAction)
},
"configCompleteRedirectUrl": string,
// Indicates that this event is dialog-related.
"isDialogEvent": true,
// Indicates that a user clicked a button, and all data
// they entered in the dialog is included in Event.common.formInputs.
"dialogEventType": "SUBMIT_DIALOG",
"common": {
"userLocale": string,
"hostApp": enum (HostApp),
"platform": enum (Platform),
"timeZone": {
object (TimeZone)
},
// Represents user data entered in a dialog.
"formInputs": {
// Represents user data entered for a specific field in a dialog.
"NAME": {
// Represents string data entered in a dialog, like text input fields
// and check boxes.
"stringInputs": {
// An array of strings entered by the user in a dialog.
"value": [
string
]
}
}
},
"parameters": {
string: string,
...
},
"invokedFunction": string
}
}
Menanggapi data yang dikumpulkan dari pesan atau dialog kartu
Setelah menerima data dari pesan atau dialog kartu, aplikasi Chat akan merespons dengan mengonfirmasi tanda terima atau dengan
menampilkan error, keduanya dilakukan dengan menampilkan
ActionResponse
:
- Untuk mengonfirmasi tanda terima yang berhasil, respons dengan parameter
ActionResponse
yang memiliki"actionStatus": "OK"
. - Untuk menampilkan error, respons dengan
parameter
ActionResponse
yang memiliki"actionStatus": "ERROR MESSAGE"
.
Contoh
Contoh berikut memeriksa keberadaan nilai name
. Jika tidak ada, aplikasi akan menampilkan error. Jika ada, aplikasi akan mengonfirmasi penerimaan data formulir
dan menutup dialog.
Node.js
/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function receiveDialog(event) {
// Checks to make sure the user entered a name
// in a dialog. If no name value detected, returns
// an error message.
if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
res.json({
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "Don't forget to name your new contact!"
}
}
});
// Otherwise the app indicates that it received
// form data from the dialog. Any value other than "OK"
// gets returned as an error. "OK" is interpreted as
// code 200, and the dialog closes.
} else {
res.json({
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
});
}
}
Apps Script
Contoh ini mengirim pesan kartu dengan menampilkan JSON kartu. Anda juga dapat menggunakan layanan kartu Apps Script.
/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function receiveDialog(event) {
// Checks to make sure the user entered a name
// in a dialog. If no name value detected, returns
// an error message.
if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "Don't forget to name your new contact!"
}
}
};
// Otherwise the app indicates that it received
// form data from the dialog. Any value other than "OK"
// gets returned as an error. "OK" is interpreted as
// code 200, and the dialog closes.
} else {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
};
}
}
Python
def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
"""Checks for a form input error, the absence of a "name" value, and returns
an error if absent. Otherwise, confirms successful receipt of a dialog.
Args:
event (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: the response.
"""
if common := event.get('common'):
if form_inputs := common.get('formInputs'):
if contact_name := form_inputs.get('WIDGET_NAME'):
if string_inputs := contact_name.get('stringInputs'):
if name := string_inputs.get('value')[0]:
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': 'OK'
}
}
}
else:
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': 'Don\'t forget to name your new contact!'
}
}
}
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.