En esta página, se describe cómo tu app de Chat puede abrir diálogos para responder a los usuarios.
Los diálogos son interfaces basadas en tarjetas y con ventanas que se abren desde un mensaje o espacio de Chat. El diálogo y su solo el usuario que lo abrió puede verlo.
Las apps de chat pueden usar diálogos para solicitar y recopilar información de Usuarios de Chat, incluidos los formularios de varios pasos. Más información para crear entradas de formulario, consulta Cómo recopilar y procesar información de los usuarios.
Requisitos previos
Node.js
- Una app de Google Chat habilitada para funciones interactivas. Para crear un app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.
Python
- Una app de Google Chat habilitada para funciones interactivas. Para crear un app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.
Apps Script
- Una app de Google Chat habilitada para funciones interactivas. Para crear un app de Chat interactiva en Apps Script, completa esta guía de inicio rápido.
Abrir un diálogo
![Un diálogo que muestra una variedad de widgets diferentes.](https://developers.google.cn/static/workspace/chat/images/dialogs-card-1.png?authuser=7&hl=es-419)
![](https://developers.google.cn/static/workspace/chat/images/dialogs-card-1.png?authuser=7&hl=es-419)
En esta sección, se explica cómo responder y configurar un diálogo de la siguiente manera:
- Activa la solicitud de diálogo a partir de una interacción del usuario.
- Para controlar la solicitud, muestra y abre un diálogo.
- Después de que los usuarios envíen la información, procesa el envío cerrando los o mostrar otro.
Activa una solicitud de diálogo
Una app de Chat solo puede abrir diálogos para responder a un usuario como un comando de barra o un clic en un botón desde un mensaje en una tarjeta.
Para responder a los usuarios con un diálogo, una app de Chat debe compila una interacción que active la solicitud de diálogo, como la siguiente:
- Responde a un comando de barra. Para activar la solicitud desde un comando de barra, debes marcar la casilla de verificación Abre un diálogo cuando configures el comando.
- Responder a un clic en un botón
mensaje,
como parte de una tarjeta o en la parte inferior del mensaje. Para activar
desde un botón en un mensaje, debes configurar
onClick
del botón la acción estableciendo suinteraction
enOPEN_DIALOG
. - Responde a un clic en un botón en la página principal de una app de Chat. Para obtener más información sobre cómo abrir diálogos desde páginas principales, consulta Crea una página principal para tu app de Google Chat.
![Botón que activa un diálogo](https://developers.google.cn/static/workspace/chat/images/dialogs-open-card-click.png?authuser=7&hl=es-419)
/addContact
. El mensaje también incluye un botón en el que los usuarios pueden hacer clic para activar el comando.
El siguiente JSON muestra cómo activar una solicitud de diálogo desde un botón en una
mensaje de tarjeta. Para abrir el diálogo,
button.interaction
se establece en OPEN_DIALOG
:
{
"buttonList": { "buttons": [{
"text": "BUTTON_TEXT",
"onClick": { "action": {
"function": "FUNCTION_NAME",
"interaction": "OPEN_DIALOG"
}}
}]}
}
Donde BUTTON_TEXT es el texto que se muestra en el botón y FUNCTION_NAME es la función que se ejecuta para abrir la configuración .
Abrir el diálogo inicial
Cuando un usuario activa una solicitud de diálogo, tu app de Chat
recibe un evento de interacción, representado como un
event
escribe
API de Chat. Si la interacción activa una solicitud de diálogo, el nombre
El campo dialogEventType
está configurado como REQUEST_DIALOG
.
Para abrir un diálogo, tu app de Chat puede responder al
de respuesta mostrando un
actionResponse
objeto con el type
establecido en DIALOG
y
Message
. Para especificar el contenido del diálogo, incluye lo siguiente
objetos:
- Un objeto
actionResponse
objeto, con sutype
establecido enDIALOG
. - Un objeto
dialogAction
. El campobody
contiene los elementos de la interfaz de usuario (IU) para mostrar en la tarjeta, incluidos uno o mássections
de widgets. Para recopilar información de los usuarios, puedes especificar widgets de entrada de formulario y una de botones. Para obtener más información sobre el diseño de entradas de formulario, consulta Recopila y procesa información de los usuarios.
En el siguiente JSON, se muestra cómo se devuelve una app de Chat una respuesta que abre un diálogo:
{ "actionResponse": {
"type": "DIALOG",
"dialogAction": { "dialog": { "body": { "sections": [{
"widgets": [{
WIDGETS,
{ "buttonList": { "buttons": [{
"text": "BUTTON_TEXT",
"onClick": {
"action": {"function": "FUNCTION_NAME"}
}
}]}}
}]
}]}}}
}}
Donde BUTTON_TEXT es el texto que se muestra en el botón (como
Next
o Submit
), WIDGETS representa uno o más.
widgets de entradas de formularios
FUNCTION_NAME es la función que se ejecuta cuando los usuarios hacen clic en un botón.
Cómo controlar el envío del diálogo
Cuando los usuarios hacen clic en un botón que envía un diálogo, tus
La app de Chat recibe
una interacción de CARD_CLICKED
evento en el que el dialogEventType
es SUBMIT_DIALOG
.
Tu app de Chat debe controlar el evento de interacción antes del realizando una de las siguientes acciones:
- Devolver otro diálogo para completar otra tarjeta o formulario.
- Cierra el diálogo después de validar los datos que envió el usuario. De forma opcional, envía un mensaje de confirmación.
Opcional: Devuelve otro diálogo
Después de que los usuarios envían el diálogo inicial, las apps de Chat pueden devolver uno o más diálogos adicionales para ayudar a los usuarios a revisar la información antes enviar formularios de varios pasos o completar formularios de varios pasos de forma dinámica.
Para cargar los datos que ingresan los usuarios desde el diálogo inicial, debes agregar
parámetros al botón que abre el siguiente diálogo, o pasa el original
CARD_CLICKED
evento de interacción del diálogo inicial. Para obtener más información, consulta
Transfiere datos a otra tarjeta.
En este ejemplo, una app de Chat abre un diálogo que
Devuelve un segundo diálogo antes de enviar. Para cargar los datos de entrada,
La app de Chat pasa el evento de interacción CARD_CLICKED
como parámetro para la función que abre el siguiente diálogo:
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
En este ejemplo, se envía un mensaje de tarjeta mostrando JSON de la tarjeta. También puedes usar Servicio de tarjetas de 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"
}}
}]}
}
]}]}}}
}};
}
Donde WIDGETS representa uno o más. widgets de entrada de formulario.
Cerrar el diálogo
Cuando los usuarios hacen clic en un botón de un diálogo, Chat recibe un evento de interacción con el la siguiente información:
eventType
esCARD_CLICKED
.dialogEventType
esSUBMIT_DIALOG
.common.formInputs
contiene cualquier dato que los usuarios ingresen con widgets.
Las siguientes secciones explican cómo validar los datos que ingresan los usuarios y cerrar el diálogo.
Valida los datos de entrada del usuario y cierra el diálogo
Para procesar los datos que ingresan los usuarios, la app de Chat
usa el
event.common.formInputs
. Si quieres obtener más información para recuperar valores de widgets de entrada, consulta
Recopila y procesa información de los usuarios.
Si el usuario omite un campo obligatorio o ingresa valores incorrectos,
La app de Chat puede responder con un error devolviendo
ActionResponse
que tiene "actionStatus": "ERROR MESSAGE"
.
En el siguiente ejemplo, se verifica que un usuario ingrese un valor para un widget que
acepta cadenas (stringInputs
), como un widget textInput
. Si no se incluye, el
La app de Chat muestra un error. Si está presente,
la app de Chat reconoce el envío del diálogo
cierra el diálogo:
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
En este ejemplo, se envía un mensaje de tarjeta mostrando JSON de la tarjeta. También puedes usar Servicio de tarjetas de 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"
}
}
};
}
}
En este ejemplo, WIDGET_NAME representa el campo name
de la
(como contactName
), y ERROR_MESSAGE representa la
el contenido del mensaje de error (como Don't forget to name your contact
).
Para obtener más información sobre cómo procesar datos de entrada de widgets, consulta
Recibe datos de widgets interactivos.
Opcional: Envía un mensaje de confirmación
Cuando cierres el diálogo, también podrás enviar un nuevo mensaje o actualizar un una existente.
Para enviar un mensaje nuevo, devuelve un
ActionResponse
objeto con type
configurado como NEW_MESSAGE
. Por ejemplo, para cerrar el diálogo
y envías un mensaje de texto, devuelve lo siguiente:
{
"actionResponse": {
"type": "NEW_MESSAGE",
},
"text": "Your information has been submitted."
}
Para actualizar un mensaje, muestra un objeto actionResponse
que contenga el
actualizado y establece la type
en una de las siguientes opciones:
UPDATE_MESSAGE
: Actualiza el mensaje que activó la solicitud de diálogo.UPDATE_USER_MESSAGE_CARDS
: Actualiza la tarjeta desde un vista previa del vínculo.
Solucionar problemas
Cuando una app de Google Chat o card muestra un error, el En la interfaz de Chat, aparece un mensaje que dice “Se produjo un error”. o "No se pudo procesar la solicitud". A veces, la IU de Chat no muestra ningún mensaje de error, pero la app de Chat la tarjeta produce un resultado inesperado; Por ejemplo, es posible que un mensaje de tarjeta no para que aparezca la opción.
Aunque es posible que no aparezca un mensaje de error en la IU de Chat, Hay mensajes de error descriptivos y datos de registro disponibles para ayudarte a corregir errores. Cuando se activa el registro de errores de las apps de Chat. Para obtener ayuda sobre la visualización, la depuración y la corrección de errores, consulta Soluciona problemas y corrige errores de Google Chat.
Temas relacionados
- Abre diálogos desde la página principal de la app de Google Chat.
- Consulta ejemplos de la app de Chat que usan diálogos
- Vista previa de los vínculos
- Cómo configurar y responder comandos de barra
- Procesa la información que ingresan los usuarios