Slack
Esto es lo que sucede cuando se utiliza Slack como canal para el asistente digital (o aptitud autónoma):
- Slack aloja el asistente digital a través del intermediario de una aplicación de Slack.
- Los usuarios chatean con el asistente digital a través de la aplicación de Slack de la interfaz de usuario de Slack.
Consulte la sección Creación de aplicaciones de Slack para ver la documentación del desarrollador de Slack para aplicaciones de Slack.
A continuación, se muestran los pasos para crear un canal de Slack para Digital Assistant.
Las aptitudes y los asistentes digitales que muestre a través de canales de Slack también se pueden incluir en los chats del grupo. Consulte Chats de grupo.
Paso 1: obtención de un espacio de trabajo en Slack
Para que el asistente digital (o el bot autónomo) esté disponible en Slack, necesita un espacio de trabajo de Slack a su disposición, donde cuente con los permisos necesarios para crear una aplicación de Slack.
Si no dispone de dicho espacio de trabajo, puede crear uno. Consulte la página Creación de un nuevo espacio de trabajo de Slack.
Paso 2: creación de una aplicación de Slack
-
Vaya a la página Your Apps de Slack.
-
Haga clic en Crear una aplicación de Slack y, a continuación, seleccione Desde cero.
-
En el cuadro de diálogo Create a Slack App, rellene los campos App Name y Development Slack Workspace y haga clic en Create App.
Una vez creada la aplicación, se muestra la página Basic Information.
-
Desplácese a la sección App Credentials de la página y anote los valores de Client ID, Client Secret y Signing Secret.
Necesitará estas credenciales para configurar el canal en Digital Assistant.
Paso 3: Adición de ámbitos de OAuth para la aplicación Slack
Agregue ámbitos de OAuth para los permisos que desea otorgar al bot y al usuario.
-
En la navegación izquierda de la consola web de la aplicación de Slack, dentro de la sección Features, seleccione OAuth y permisos.
-
Desplácese a la sección Scopes de la página.
-
Los ámbitos entran en las siguientes categorías:
- Ámbitos de token de bot
- Ámbitos de token de usuario
-
En la sección Ámbitos de token de bot, agregue los ámbitos que corresponden a los permisos de nivel de bot que desea permitir. Como mínimo, se necesitan los siguientes ámbitos de token de bot:
chat:write
im:history
users:read
Dependiendo de las características de la aptitud, es posible que se necesiten otros ámbitos. Por ejemplo, los siguientes ámbitos son necesarios para trabajar con asociaciones:
files:read
files:write
-
En la sección Ámbitos de token de usuario, agregue los ámbitos que corresponden a los permisos de nivel de usuario que desea permitir. Se necesitan los siguientes ámbitos de token de usuario:
files:read
files:write
Dependiendo de los requisitos del bot, puede que deba agregar otros ámbitos.
Paso 4: adición de la aplicación al espacio de trabajo
-
Vuelva a la parte superior de la página OAuth & Permissions.
-
En la sección OAuth Tokens & Redirect URLs, haga clic en Install to Workspace.
Aparecerá una página en la que se mostrará lo que podrá hacer la aplicación.
-
En la parte inferior de la página, haga clic en Allow.
Una vez completado este paso, debe poder ver la aplicación en el espacio de trabajo de Slack seleccionando Apps en la navegación izquierda.
Paso 5: creación de un canal en Digital Assistant
-
En Digital Assistant, haga clic en Canales en el menú de la izquierda y, a continuación, seleccione Usuarios.
-
Haga clic en Agregar canal para abrir el cuadro de diálogo Crear canal.
-
Asigne un nombre al canal.
-
Seleccione Slack como tipo de canal.
-
Rellene los valores de ID de cliente, Secreto de cliente y Secreto de firma obtenidos al crear la aplicación de Slack.
Puede recuperar estos valores en la página Settings de la aplicación de Slack.
- Si está configurando el canal para los chats de grupo y desea que los mensajes vayan al grupo sin mencionar el nombre de la aplicación Slack, seleccione Permitir mensajes sin mención de aplicación en chat de grupo.
-
Haga clic en Crear.
-
En la página Canales, copie el URL del webhook y péguelo en algún lugar del sistema de fácil acceso. Necesitará estos datos para terminar de configurar la aplicación de Slack.
-
Haga clic en
y seleccione el asistente digital o la aptitud que desea asociar al canal.
-
En el desplegable Encaminar a, seleccione el asistente digital o la aptitud que quiera asociar al canal.
- Active el control Canal activado.
Paso 6: configuración del URL del webhook en la aplicación de Slack
-
En la navegación izquierda de la consola web de la aplicación Slack, seleccione Interactivity & Shortcuts.
-
Active el conmutador Interactivity.
-
En los campos Request URL y Options Load URL, pegue el URL del webhook generado al crear el canal en Digital Assistant .
-
Haga clic en Save Changes.
-
En la navegación izquierda, seleccione OAuth & Permissions.
-
En el campo Redirect URLs, haga clic en Add New Redirect URL.
-
Pegue la URL de webhook, agregue
/authorizeV2
y haga clic en Add. -
Haga clic en Save URLs.
-
En la navegación izquierda, seleccione App Home.
-
En la sección Your App’s Presence in Slack, active el conmutador Always Show My Bot as Online.
-
Desplácese hacia abajo en la página hasta la sección Mostrar separadores y active el conmutador Separador Mensajes.
-
Seleccione la casilla de control Permitir a los usuarios enviar comandos y mensajes de barra diagonal desde el separador Mensajes.
-
En la navegación izquierda, seleccione Event Subscriptions.
-
Active el conmutador Enable Events.
-
En el campo Request URL, pegue el URL del webhook.
Tras introducir el URL, debería aparecer una etiqueta Verified de color verde junto al campo Request URL.
-
Expanda la sección Suscribirse a eventos de bot de la página, haga clic en Agregar evento de usuario de bot y agregue el siguiente evento:
message.im
- Si tiene previsto hacer que el bot esté disponible en chats de grupo, agregue también los siguientes eventos:
app_mention
message.mpim
message.channels
-
Haga clic en Save Changes.
-
En la navegación izquierda, seleccione Manage Distribution.
-
Haga clic en el botón Add to Slack y, a continuación, en Allow.
En este momento, debe mostrarse el mensaje You've successfully installed your App in Slack.
Paso 7: prueba del bot en Slack
Una vez completada la configuración de la mensajería y el canal de Slack, puede probar el bot (asistente digital o aptitud) en Slack.
-
Abra el espacio de trabajo de Slack en el que ha instalado la aplicación.
-
En la barra de navegación izquierda, seleccione la aplicación asociada al asistente digital.
- En el campo Message, introduzca el texto para empezar a comunicarse con el asistente digital.
Si ve el mensaje "El envío de mensajes a esta aplicación se ha desactivado" en el cliente de Slack, intente reiniciar la aplicación de Slack. Si esto no activa el campo, compruebe que ha otorgado todos los permisos necesarios.
Aplicaciones Slack "nuevas" frente a "clásicas"
A partir de la versión 20.6 de Oracle Digital Assistant, la creación de canales de Slack se basa en un flujo de OAuth de actualizado en aplicaciones de Slack. Este flujo actualizado permite más ámbitos granulares. Las instrucciones para la configuración del canal en esta guía se basan en el nuevo flujo de OAuth.
Consulte https://api.slack.com/authentication/oauth-v2 para obtener más información sobre el flujo de OAuth actualizado.
Los canales existentes que se hayan creado antes de Digital Assistant 20.6 y que se basen en aplicaciones de Slack "clásicas" seguirán funcionando. Sin embargo, debe considerar migrar esas aplicaciones clásicas de Slack a nuevas aplicaciones de Slack. Consulte https://api.slack.com/authentication/migration para obtener más información.
Capacidades admitidas
Los canales de Slack en Digital Assistant admiten las siguientes capacidades:
- texto (tanto envío como recepción)
- imágenes (tanto envío como recepción)
- archivos (soporte parcial para el envío, soporte completo para la recepción)
- emojis (soporte parcial para envío, soporte completo para recepción)
- enlaces
- devoluciones
- propiedades personalizadas
- componentes en carrusel (representados verticalmente, no horizontalmente)
- componentes de la lista
Slack le permite formatear mensajes con Markdown. Consulte https://api.slack.com/reference/surfaces/formatting en la documentación de la API de Slack.
Si va a dirigir la aptitud a varios canales con diferentes capacidades de formato y sintaxis, puede utilizar el marcado HTML básico en los mensajes. Si lo hace, ese marcado se convertirá automáticamente al formato de rebaja de Slack cuando el mensaje se transmita al canal. Esto es particularmente útil si está dirigiendo sus habilidades a otros canales además de Slack. Consulte Formato de texto enriquecido en canales.
Restricciones de mensajes
Los canales de Slack en Digital Assistant presentan las siguientes restricciones de mensaje:
- Mensajes de texto
- Longitud máxima del mensaje de texto: 3000 caracteres. Si la longitud supera los 3000 caracteres, el texto se dividirá en varios mensajes.
- Longitud máxima de la etiqueta de acción de texto: 30 caracteres
- Tipos de acciones de texto permitidas: devolución, URL
- Tarjetas horizontales
- ¿Se admite? No. El diseño de la tarjeta pasa a ser vertical.
- Tarjetas verticales
- Longitud máxima del título: 3000 caracteres
- Longitud máxima de la descripción: 3000 caracteres
- Longitud máxima de la etiqueta de acción de la tarjeta: 30 caracteres
- Número máximo de tarjetas: 100
- Tipos de acciones de tarjeta permitidas: retroceso, URL
- Tipos de acciones de lista de tarjetas permitidas: retroceso, URL
- Mensajes anexos
- ¿Se admite?: sí
- Tipos de acciones permitidas: devolución, URL
- Botones de acción
- Longitud máxima de la etiqueta de acción global: 30 caracteres
- Tipos de acciones globales permitidas: devolución, URL
Extensiones de canal de Slack
Para los canales de Slack, puede ampliar la funcionalidad de los componentes de respuesta común con capacidades específicas de Slack.
Para acceder a las extensiones, utilice el elemento channelCustomProperties
de los metadatos del componente de respuesta común y defina las propiedades adecuadas. El código tiene el formato siguiente:
...
channelCustomProperties:
- channel: "slack"
properties:
PROPERTY_NAME: "PROPERTY_VALUE"
...
A continuación, se muestran las propiedades personalizadas disponibles para los canales de Slack:
Nombre | Valores permitidos | Se aplica a... | Descripción |
---|---|---|---|
dropDownPlaceholder |
|
Elementos de respuesta | Utilice esta propiedad para especificar el texto del marcador de posición que se muestra en la lista desplegable. |
ephemeral |
|
Elementos de respuesta | Se puede utilizar en los chats de grupo para mostrar un mensaje a un solo usuario, por ejemplo, cuando ese usuario intenta autenticarse. |
fields |
|
Elementos de respuesta de tipo text .
|
Los valores de cadena especificados en esta propiedad se muestran como campos en un diseño de dos columnas (escritorio) o en un diseño de una sola columna (móvil). |
renderActionsAsDropDown |
|
Elementos de respuesta | Por defecto (si no define esta propiedad), las acciones se muestran:
Si desea mostrar las acciones en una lista desplegable, independientemente de cuántas acciones haya, defina esta propiedad en Si desea mostrar las acciones como botones, independientemente de cuántas acciones haya, defina esta propiedad en Si quiere que el comportamiento sea diferente según los distintos tipos de acciones de devolución, puede utilizar un objeto anidado con valores booleanos para cada uno de los siguientes tipos de acciones:
Para representar acciones en un menú desplegable, Slack utiliza un menú de selección con elementos estáticos. Consulte https://api.slack.com/reference/messaging/block-elements#static-select. |
showDatePicker |
|
Elementos de respuesta de tipo text .
|
Defínala en true para mostrar un selector de fecha junto al mensaje de texto.
En el cuadro de diálogo Agregar estado, puede seleccionar la plantilla Selector de fecha de Slack para obtener el código de ejemplo para mostrar un selector de fecha de forma condicional. Consulte también https://api.slack.com/reference/messaging/block-elements#datepicker. |
showImageInAccessory |
|
Elementos de respuesta de tipo cards .
|
Defínala en true para mostrar la imagen de tarjeta a la derecha y como una imagen pequeña, en lugar de como una imagen centrada más grande.
|
A continuación, se muestra un ejemplo de uso de la propiedad personalizada renderActionsAsDropDown
.
responseItems:
- type:
"text"
text: "Here is a list of the UI features of the Common Response Component:"
actions:
- ...
channelCustomProperties:
- channel: "slack"
properties:
renderActionsAsDropDown: false
Este es un ejemplo de uso de la propiedad personalizada renderActionsAsDropDown
con propiedades anidadas para postbackActions
, cardPostbackActions
y globalPostbackActions
.
responseItems:
- type: "text"
text: "Here is a list of the UI features of the Common Response Component:"
actions:
- ...
channelCustomProperties:
- channel: "slack"
properties:
renderActionsAsDropDown:
postbackActions: false
cardPostbackActions: true
globalPostbackActions: true
Para obtener más información general sobre channelCustomProperties
, consulte Extensiones específicas del canal.
Módulos de Slack
Puede crear un botón para llamar a un modal de Slack en un componente de respuesta común. Para ello, defina la propiedad de acción del botón en system.openModal
e incluya una variable denominada system.dialogPayload
de tipo map
. Los metadatos de acción deben parecerse al siguiente fragmento:
actions:
- label: "Open Dialog"
type: "postback"
payload:
action: "system.openModal"
variables:
system.dialogPayload: ${dialogPayload}
La expresión de Freemarker para hacer referencia a la variable
system.dialogPayload
no termina con .value
. Esto se debe a que la variable contiene un objeto JSON y las expresiones Freemarker siempre deben evaluarse en una cadena. El uso de la expresión ${dialogPayload.value}
arrojaría un error. La conversión de objeto a cadena JSON se realiza al omitir .value
.
El valor de system.dialogPayload
se suele definir en un componente personalizado, pero también se puede definir en línea o mediante un componente Definir Variable.
Si define la variable
system.dialogPayload
en un componente personalizado, no necesita codificar los valores de entidad como opciones. En su lugar, puede iterar sobre todos los valores de entidad de un elemento específico y crear de forma dinámica un tipo de elemento exclusivo con una matriz de opciones para los valores permitidos.
Cuando el usuario envía la entrada en el diálogo de Slack, el componente de respuesta común define la transición system.dialogSubmitted
para pasar a un estado que procese los valores enviados. Los valores enviados se almacenan en variables con el mismo nombre.
Le corresponde a usted determinar cómo procesar los valores de campo enviados. El componente Respuesta Común NO realiza ninguna actualización automática de los valores de entidad. Solo almacena los valores en variables. Normalmente procesará estos valores en un componente personalizado, por lo que puede realizar validaciones adicionales si es necesario. En su forma más sencilla, puede almacenar los valores de campo enviados en una variable de cadena y, a continuación, utilizar el componente Entidad de Coincidencia para actualizar los valores de entidad.
Consejo:
En el editor de flujo de diálogo (en el modo de diálogo Visual y YAML), hay una plantilla de Slack Block Kit que contiene un ejemplo de metadatos muy anidado que es típico de la salida del creador de kits. Si necesita metadatos complejos para dicho estado y desea facilitar su lectura, puede utilizar variables de mapa de nivel de flujo, pegar objetos JSON completos generados por el creador de kits en ellos como valores por defecto e incorporar las variables en los metadatos.Para obtener documentación completa sobre los tipos de elementos soportados en la carga útil del cuadro de diálogo de Slack, consulte https://api.slack.com/reference/block-kit/block-elements. La estructura que especifique en la carga útil de diálogo debe ser idéntica a la estructura descrita en la documentación de Slack.
El diálogo Slack también soporta el envío de una matriz de errores como respuesta cuando se envía el modal. Sin embargo, esta funcionalidad no está soportada actualmente en los componentes de respuesta común. En su lugar, debe gestionar la validación personalizada y los comentarios de usuario asociados a los errores de validación en un componente personalizado.
Ventana de diálogo de Slack
Slack ahora recomienda utilizar modales de Slack en lugar de cuadros de diálogo de Slack. Consulte Slack Modals para obtener detalles sobre la incorporación de los módales de Slack al flujo de diálogo y https://api.slack.com/block-kit/dialogs-to-modals para obtener información sobre la conversión de cuadros de diálogo a módales.
Puede crear un botón para llamar a un diálogo de Slack en un componente de respuesta común. Para ello, defina la propiedad de acción del botón en system.openDialog
e incluya una variable denominada system.dialogPayload
. Los metadatos de acción deben parecerse al siguiente fragmento:
actions:
- label: "Edit"
type: "postback"
payload:
action: "system.openDialog"
variables:
system.dialogPayload: ${dialogPayload}
La expresión de Freemarker para hacer referencia a la variable
system.dialogPayload
no termina con .value
. Esto se debe a que la variable contiene un objeto JSON y las expresiones Freemarker siempre deben evaluarse en una cadena. El uso de la expresión ${dialogPayload.value}
arrojaría un error. La conversión de objeto a cadena JSON se realiza al omitir .value
.
El valor de system.dialogPayload
se suele definir en un componente personalizado, pero también se puede definir en línea o mediante un componente Definir Variable.
Si define la variable
system.dialogPayload
en un componente personalizado, no necesita codificar los valores de entidad como opciones. En su lugar, puede iterar sobre todos los valores de entidad de un elemento específico y crear de forma dinámica un tipo de elemento exclusivo con una matriz de opciones para los valores permitidos.
Cuando el usuario envía la entrada en el diálogo de Slack, el componente de respuesta común define la transición system.dialogSubmitted
para pasar a un estado que procese los valores enviados. Los valores enviados se almacenan en variables de flujo de diálogo con el mismo nombre.
Le corresponde a usted determinar cómo procesar los valores de campo enviados. El componente Respuesta Común NO realiza ninguna actualización automática de los valores de entidad. Solo almacena los valores en variables de flujo de diálogo. Normalmente procesará estos valores en un componente personalizado, por lo que puede realizar validaciones adicionales si es necesario. En su forma más sencilla, puede almacenar los valores de campo enviados en una variable de cadena y, a continuación, utilizar el componente Entidad de Coincidencia para actualizar los valores de entidad.
Para obtener la documentación sobre otras propiedades y tipos de elementos soportados en la carga útil del diálogo de Slack, consulte https://api.slack.com/dialogs#top-level_dialog_attributes. La estructura de la carga útil de diálogo debe ser idéntica a la estructura descrita en la documentación de Slack.
El diálogo Slack también soporta el envío de una matriz de errores como respuesta cuando se envía el diálogo. Sin embargo, esta funcionalidad no está soportada actualmente en los componentes de respuesta común. En su lugar, debe gestionar la validación personalizada y los comentarios de usuario asociados a los errores de validación en un componente personalizado.