このガイドでは、ユーザーがカード メッセージとダイアログに入力した情報を受け取り、確認する方法について説明します。ユーザーは、Chat アプリが受信、読み取り、応答するデータを入力できます。ユーザーが情報を入力できるウィジェットには次のものがあります。
TextInput
: 候補もサポートする自由形式のテキスト入力用。SelectionInput
: リストアイテムとメニュー(チェックボックス、ラジオボタン、プルダウン メニューなど)用。DateTimePicker
: 日付と時刻のエントリ。
カードビルダーを使用して、Chat アプリ用の JSON カード メッセージを設計し、プレビューします。
カードビルダーを開くユーザーからデータ入力を受け取ると、Chat アプリは次の処理を実行できます。
- カスタマー サービスのケースを更新する。
- 作業指示を作成する。
- ウェブサービスで認証する。
データの受信の仕組み
Chat アプリは、情報をダイアログまたはカード メッセージとしてユーザーに提示します。この例では、ユーザーに TextInput
ウィジェットと SelectionInput
ウィジェットを使用して連絡先に関する情報を入力するように求めるダイアログが表示されています。
完了すると、Chat アプリは、ユーザーがダイアログに入力した JSON 形式のデータとインタラクション イベントを受け取ります。
EventType
はCARD_CLICKED
です。DialogEventType
はSUBMIT_DIALOG
です(ダイアログの場合のみ)。
ユーザーが入力した内容に関するデータを取得するには、イベント ペイロードの Event.common.formInputs
フィールドを使用します。formInputs
フィールドはマップです。キーは各ウィジェットに割り当てられた文字列 ID で、値は各ウィジェットのユーザー入力を表します。さまざまなオブジェクトが異なる入力データ型を表します。たとえば、Event.common.formInputs.stringInputs
は文字列入力を表します。
アプリは event.common.formInputs.NAME.stringInputs.value[0]
で最初にユーザーが入力した値にアクセスできます。ここで、NAME
は TextInput
ウィジェットの name
フィールドです。
カードからデータを受け取る
ユーザーがカード メッセージにデータを入力すると、Chat アプリは、次の例のように Chat アプリのインタラクション イベントを受信します。
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
}
}
ダイアログからデータを受け取る
ユーザーがダイアログでデータを送信すると、Chat アプリは、次の例のように別の Chat アプリのインタラクション イベントを受け取ります。
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
}
}
カード メッセージやダイアログから収集したデータに応答する
カード メッセージまたはダイアログからデータを受信すると、Chat アプリは、受信の確認応答またはエラーを返して応答します。どちらの場合も ActionResponse
を返します。
- 受信が正常に行われたことを確認するには、
"actionStatus": "OK"
を含むActionResponse
パラメータを返します。 - エラーを返すには、
"actionStatus": "ERROR MESSAGE"
を含むActionResponse
パラメータを返します。
例
次の例では、name
値の有無を確認します。存在しない場合は、エラーが返されます。存在する場合、アプリはフォームデータの受信を確認し、ダイアログを閉じます。
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
この例では、カード JSON を返してカード メッセージを送信します。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!'
}
}
}
トラブルシューティング
Google Chat アプリまたはカードからエラーが返されると、Chat インターフェースに「エラーが発生しました」というメッセージが表示されます。または「リクエストを処理できません」と表示されます。Chat UI にエラー メッセージが表示されていなくても、Chat アプリまたはカードから予期しない結果(カード メッセージが表示されないなど)が生成される場合があります。
エラー メッセージは Chat UI に表示されない場合がありますが、Chat アプリのエラーロギングがオンになっている場合は、エラー メッセージとログデータを使用してエラーを修正できます。エラーの表示、デバッグ、修正については、Google Chat のエラーのトラブルシューティングと修正をご覧ください。