In questa pagina viene descritto come l'app Chat può aprire le finestre di dialogo per rispondere agli utenti.
Le finestre di dialogo sono interfacce basate su schede con finestre che si aprono da uno spazio di Chat o da un messaggio. La finestra di dialogo e i relativi sono visibili solo all'utente che li ha aperti.
Le app di chat possono utilizzare le finestre di dialogo per richiedere e raccogliere informazioni da Utenti di Chat, inclusi i moduli con più passaggi. Per maggiori dettagli sulla creazione degli input dei moduli, consulta Raccogliere ed elaborare informazioni dagli utenti.
Prerequisiti
Node.js
- Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un un'app di chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.
Python
- Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un un'app di chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.
Apps Script
- Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un app di Chat interattiva in Apps Script, completa questa guida rapida.
Apri una finestra di dialogo
In questa sezione viene spiegato come rispondere e impostare una finestra di dialogo:
- Attiva la richiesta di finestra di dialogo da un'interazione utente.
- Per gestire la richiesta, restituisci e apri una finestra di dialogo.
- Dopo che gli utenti avranno inviato le informazioni, elaborale chiudendo finestra di dialogo o la restituzione di un'altra finestra di dialogo.
Attiva una richiesta di finestra di dialogo
Un'app di Chat può aprire le finestre di dialogo solo per rispondere a un utente un'interazione, come un comando slash o un clic su un pulsante da un messaggio in una scheda.
Per rispondere agli utenti con una finestra di dialogo, un'app di Chat deve crea un'interazione che attivi la richiesta di dialogo, ad esempio:
- Rispondi a un comando slash. Per attivare la richiesta da un comando slash, devi selezionare la casella di controllo Apre una finestra di dialogo durante la configurazione del comando.
- Rispondere a un clic su un pulsante in una
messaggio,
all'interno di una scheda o in fondo al messaggio. Per attivare il parametro
richiesta da un pulsante in un messaggio, configuri
onClick
del pulsante impostandointeraction
suOPEN_DIALOG
. - Rispondere a un clic su un pulsante nella home page di un'app di Chat. Per ulteriori informazioni sull'apertura di finestre di dialogo dalle home page, consulta: Crea una home page per l'app Google Chat.
Il seguente JSON mostra come attivare una richiesta di dialogo da un pulsante in un
messaggio della scheda. Per aprire la finestra di dialogo, utilizza il
button.interaction
è impostato su OPEN_DIALOG
:
{
"buttonList": { "buttons": [{
"text": "BUTTON_TEXT",
"onClick": { "action": {
"function": "FUNCTION_NAME",
"interaction": "OPEN_DIALOG"
}}
}]}
}
Dove BUTTON_TEXT è il testo visualizzato nel pulsante e FUNCTION_NAME è la funzione che esegue per aprire l'iniziale .
Apri la finestra di dialogo iniziale
Quando un utente attiva una richiesta di dialogo, la tua app Chat
riceve un evento di interazione, rappresentato come
event
digita
API Chat. Se l'interazione attiva una richiesta di dialogo, l'evento
Il campo dialogEventType
è impostato su REQUEST_DIALOG
.
Per aprire una finestra di dialogo, l'app Chat può rispondere al
restituendo una richiesta
actionResponse
con type
impostato su DIALOG
e
Message
. Per specificare i contenuti della finestra di dialogo, includi quanto segue
oggetti:
- Un
actionResponse
con il valoretype
impostato suDIALOG
. - Un
dialogAction
. Il campobody
contiene gli elementi dell'interfaccia utente (UI) per visualizzare nella scheda, inclusi uno o piùsections
di widget. Per raccogliere informazioni dagli utenti, puoi specificare widget di input del modulo e un widget del pulsante. Per scoprire di più sulla progettazione degli input di modulo, consulta Raccogliere ed elaborare informazioni dagli utenti.
Il seguente JSON mostra come restituisce un'app di Chat una risposta che apre una finestra di dialogo:
{ "actionResponse": {
"type": "DIALOG",
"dialogAction": { "dialog": { "body": { "sections": [{
"widgets": [{
WIDGETS,
{ "buttonList": { "buttons": [{
"text": "BUTTON_TEXT",
"onClick": {
"action": {"function": "FUNCTION_NAME"}
}
}]}}
}]
}]}}}
}}
Dove BUTTON_TEXT è il testo visualizzato nel pulsante (ad esempio
Next
o Submit
), WIDGETS rappresenta uno o più
widget di input del modulo e
FUNCTION_NAME è la funzione che viene eseguita quando gli utenti fanno clic su un pulsante.
Gestire l'invio della finestra di dialogo
Quando gli utenti fanno clic su un pulsante che invia una finestra di dialogo,
L'app di chat riceve
un'interazione con CARD_CLICKED
evento in cui dialogEventType
è SUBMIT_DIALOG
.
L'app Chat deve gestire l'evento di interazione nel effettuando una delle seguenti operazioni:
- Restituisci un'altra finestra di dialogo per compilare un'altra scheda o modulo.
- Chiudi la finestra di dialogo dopo aver convalidato i dati inviati dall'utente e invia un messaggio di conferma (facoltativo).
(Facoltativo) Restituire un'altra finestra di dialogo
Dopo che gli utenti hanno inviato la finestra di dialogo iniziale, le app di chat possono restituire una o più finestre di dialogo aggiuntive per aiutare gli utenti a rivedere le informazioni prima l'invio, la compilazione di moduli con più passaggi o la compilazione dinamica dei contenuti.
Per caricare i dati inseriti dagli utenti dalla finestra di dialogo iniziale, devi aggiungere
parametri al pulsante che apre la finestra di dialogo successiva o trasmettere l'originale
CARD_CLICKED
evento di interazione dalla finestra di dialogo iniziale. Per maggiori dettagli, vedi
Trasferire i dati su un'altra carta.
In questo esempio, un'app di Chat apre una finestra di dialogo
restituisce una seconda finestra di dialogo prima dell'invio. Per caricare i dati di input,
L'app di Chat supera l'evento di interazione CARD_CLICKED
come parametro per la funzione che apre la finestra di dialogo successiva:
Node.js
// Respond to button clicks on attached cards
if (event.type === "CARD_CLICKED") {
// Open the first dialog.
if (event.common.invokedFunction === "openDialog") {
openDialog(event);
}
// Open the second dialog.
if (event.common.invokedFunction === "openNextDialog") {
openNextDialog(event);
}
}
/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
res.json({ "actionResponse": {
"type": "DIALOG",
"dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
WIDGETS,
{ "buttonList": { "buttons": [{
"text": "Next",
"onClick": { "action": {
"function": "openNextDialog"
}}
}]}}
]}]}}}
}});
};
/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
res.json({ "actionResponse": {
"type": "DIALOG",
"dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
WIDGETS,
{
"horizontalAlignment": "END",
"buttonList": { "buttons": [{
"text": "Submit",
"onClick": { "action": {
"function": "submitDialog"
}}
}]}
}
]}]}}}
}});
}
Python
from typing import Any, Mapping
import flask
import functions_framework
@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
"""Responds to a MESSAGE event in Google Chat that includes the /createContact
slash command by opening a dialog.
Args:
req (flask.Request): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
if req.method == 'GET':
return 'Sorry, this function must be called from a Google Chat.'
request = req.get_json(silent=True)
if request.get('type') == 'CARD_CLICKED':
if invoked_function := request.get('common', dict()).get('invokedFunction'):
if invoked_function == 'open_dialog':
return open_dialog(request)
elif invoked_function == 'open_next_dialog':
return open_dialog(request)
def open_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
"""Opens a dialog in Google Chat.
Args:
request (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
return { "actionResponse": {
"type": "DIALOG",
"dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
WIDGETS,
{ "buttonList": { "buttons": [{
"text": "Next",
"onClick": { "action": {
"function": "open_next_dialog"
}}
}]}}
]}]}}}
}}
def open_next_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
"""Opens a second dialog that lets users add more contact details.
Args:
request (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
return { "actionResponse": {
"type": "DIALOG",
"dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
WIDGETS,
{
"horizontalAlignment": "END",
"buttonList": { "buttons": [{
"text": "Submit",
"onClick": { "action": {
"function": "submit_dialog"
}}
}]}
}
]}]}}}
}}
Apps Script
Questo esempio invia un messaggio di una scheda restituendo JSON card. Puoi utilizzare anche Servizio di schede Apps Script.
/**
* Responds to a CARD_CLICKED event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onCardClick(event) {
// When a user clicks a card, the Chat app checks to see which function to run.
if (event.common.invokedFunction === "openDialog") {
return openDialog(event);
}
if (event.common.invokedFunction === "openNextDialog") {
return openNextDialog(event);
}
}
/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
return { "actionResponse": {
"type": "DIALOG",
"dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
WIDGETS,
{ "buttonList": { "buttons": [{
"text": "Next",
"onClick": { "action": {
"function": "openNextDialog"
}}
}]}}
]}]}}}
}};
}
/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
return { "actionResponse": {
"type": "DIALOG",
"dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
WIDGETS,
{
"horizontalAlignment": "END",
"buttonList": { "buttons": [{
"text": "Submit",
"onClick": { "action": {
"function": "submitDialog"
}}
}]}
}
]}]}}}
}};
}
Dove WIDGETS rappresenta uno o più widget di input modulo.
Chiudi la finestra di dialogo
Quando gli utenti fanno clic su un pulsante in una finestra di dialogo, L'app Chat riceve un evento di interazione con le seguenti informazioni:
eventType
èCARD_CLICKED
.dialogEventType
èSUBMIT_DIALOG
.common.formInputs
contiene tutti i dati inseriti dagli utenti utilizzando i widget.
Le seguenti sezioni spiegano come convalidare i dati inseriti e chiudi la finestra di dialogo.
Convalida i dati di input dell'utente e chiudi la finestra di dialogo
Per elaborare i dati inseriti dagli utenti, l'app Chat
utilizza
event.common.formInputs
. Per ulteriori informazioni sul recupero dei valori dai widget di input, consulta
Raccogliere ed elaborare informazioni dagli utenti.
Se l'utente omette un campo obbligatorio o inserisce valori errati, la
L'app di chat può rispondere con un errore restituendo un
ActionResponse
con "actionStatus": "ERROR MESSAGE"
.
L'esempio seguente verifica che un utente abbia inserito un valore per un widget che
accetta stringhe (stringInputs
), come un widget textInput
. Se non è presente,
L'app Chat restituisce un errore. Se presente,
l'app Chat conferma l'invio della finestra di dialogo e
chiude la finestra di dialogo:
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 submitDialog(event) {
// Checks to make sure the user entered a value
// in a dialog. If no value detected, returns
// an error message. Any "actionStatus" value other than "OK"
// gets returned as an error.
if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] === "") {
res.json({
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "ERROR_MESSAGE"
}
}
});
// Otherwise the Chat app indicates that it received
// form data from the dialog. An "actionStatus" of "OK" is
// interpreted as code 200, and the dialog closes.
} else {
res.json({
"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': 'ERROR_MESSAGE'
}
}
}
Apps Script
Questo esempio invia un messaggio di una scheda restituendo JSON card. Puoi utilizzare anche Servizio di schede 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 submitDialog(event) {
// Checks to make sure the user entered a value
// in a dialog. If no value detected, returns
// an error message. Any "actionStatus" value other than "OK"
// gets returned as an error.
if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] === "") {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "ERROR_MESSAGE"
}
}
};
// Otherwise the Chat app indicates that it received
// form data from the dialog. An "actionStatus" of "OK" is
// interpreted as code 200, and the dialog closes.
} else {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
};
}
}
In questo esempio, WIDGET_NAME rappresenta il campo name
del
widget (come contactName
) e ERROR_MESSAGE rappresenta il
contenuti del messaggio di errore (ad esempio Don't forget to name your contact
).
Per informazioni dettagliate sull'elaborazione dei dati di input dai widget, vedi
Ricevi dati dai widget interattivi.
(Facoltativo) Inviare un messaggio di conferma
Quando chiudi la finestra di dialogo, puoi anche inviare un nuovo messaggio o aggiornare una esistente.
Per inviare un nuovo messaggio, restituisci
ActionResponse
con type
impostato su NEW_MESSAGE
. Ad esempio, per chiudere la finestra di dialogo
e invia un SMS, restituisci quanto segue:
{
"actionResponse": {
"type": "NEW_MESSAGE",
},
"text": "Your information has been submitted."
}
Per aggiornare un messaggio, restituisci un oggetto actionResponse
che contiene il
ha aggiornato il messaggio e imposta type
su uno dei seguenti valori:
UPDATE_MESSAGE
: aggiorna il messaggio che ha attivato la richiesta di finestra di dialogo.UPDATE_USER_MESSAGE_CARDS
: aggiorna la scheda da un anteprima del link.
Risoluzione dei problemi
Quando un'app Google Chat o card restituisce un errore, L'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la richiesta". A volte, l'UI di Chat non mostra alcun messaggio di errore, ma l'app Chat o la scheda restituisce un risultato inaspettato; Ad esempio, il messaggio di una scheda potrebbe non vengono visualizzate.
Anche se un messaggio di errore potrebbe non essere visualizzato nella UI di Chat, messaggi di errore descrittivi e dati di log che ti aiuteranno a correggere gli errori quando il logging degli errori per le app di chat è attivo. Per assistenza con la visualizzazione, il debug e la correzione degli errori, consulta Risolvere i problemi e correggere gli errori di Google Chat.
Argomenti correlati
- Apri le finestre di dialogo dalla home page dell'app Google Chat.
- Visualizzare esempi di app di Chat che utilizzano finestre di dialogo
- Link di anteprima
- Configurare e rispondere ai comandi slash
- Elaborare le informazioni inserite dagli utenti