Para brindarte aún más flexibilidad a la hora de compilar acciones, puedes delegar la lógica a los servicios web HTTPS (entrega). Tus acciones pueden activar webhooks que realizan solicitudes a un extremo HTTPS. Estos son algunos ejemplos de lo que puedes hacer en la entrega:
- Generación de un mensaje dinámico basado en la información proporcionada por el usuario
- Realizar un pedido en un sistema externo y confirmar que se realizó correctamente
- Validar ranuras con datos de backend
Activadores y controladores de webhook
Tus acciones pueden activar un webhook dentro de los intents de invocación o escenas, lo que envía una solicitud al extremo de entrega. Tu entrega contiene controladores de webhook que procesan la carga útil de JSON en la solicitud. Puedes activar webhooks en las siguientes situaciones:
- Después de la coincidencia de un intent de invocación
- Durante la escena cuando entra a la escena
- Después de que una condición se evalúa como verdadera en la etapa de condición de una escena
- Durante la etapa de relleno de espacios de una escena
- Después de que se produce una coincidencia de intent en la etapa de entrada de una escena
Cuando activas un webhook en tus acciones, Asistente de Google envía una solicitud con una carga útil de JSON a la entrega, la cual contiene el nombre del controlador que se usará para procesar el evento. Tu extremo de entrega puede enrutar el evento al controlador apropiado para llevar a cabo la lógica y mostrar la respuesta con una carga útil de JSON correspondiente.
Cargas útiles
En los siguientes fragmentos, se muestran solicitudes de ejemplo que las acciones envían a la entrega y una respuesta que la entrega envía. Consulta la documentación de referencia para obtener más información.
Solicitud de ejemplo
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "example_session_id",
"params": {},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Ejemplo de respuesta
{
"session": {
"id": "example_session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "Hello World.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
}
}
Interacciones en tiempo de ejecución
En las siguientes secciones, se describen tareas comunes que puedes realizar en los controladores de webhook.
Enviar mensajes
Puedes crear mensajes con texto simple, texto enriquecido, tarjetas y hasta mensajes HTML completos respaldados por una app web con Interactive Canvas. En la documentación de mensajes, encontrarás información completa para crear un mensaje cuando se controla un evento de webhook. En los siguientes fragmentos, se muestra un mensaje de tarjeta:
Node.js
app.handle('rich_response', conv => {
conv.add('This is a card rich response.');
conv.add(new Card({
title: 'Card Title',
subtitle: 'Card Subtitle',
text: 'Card Content',
image: new Image({
url: 'https://developers.google.com/assistant/assistant_96.png',
alt: 'Google Assistant logo'
})
}));
});
Respuesta JSON
{
"session": {
"id": "example_session_id",
"params": {}
},
"prompt": {
"override": false,
"content": {
"card": {
"title": "Card Title",
"subtitle": "Card Subtitle",
"text": "Card Content",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
},
"firstSimple": {
"speech": "This is a card rich response.",
"text": ""
}
}
}
Parámetros de intents de lectura
Cuando el entorno de ejecución de Asistente coincide con un intent, extrae cualquier parámetro definido. La propiedad original era lo que el usuario proporcionó como entrada y la propiedad resuelta es a lo que la CLN resolvió la entrada según la especificación del tipo.
Node.js
conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved
Cómo solicitar JSON
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "intent_name",
"params": {
"slot_name": {
"original": "1",
"resolved": 1
}
},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
},
"session": {
"id": "session_id",
"params": {},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Leer la configuración regional del usuario
Este valor corresponde a la configuración regional del usuario para Asistente de Google.
Node.js
conv.user.locale
JSON
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "session_id",
"params": {},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Almacenamiento de lectura y escritura
Consulta la documentación de almacenamiento para obtener información completa sobre cómo usar diversas funciones de almacenamiento.
Node.js
//read
conv.session.params.key
conv.user.params.key
conv.home.params.key
// write
conv.session.params.key = value
conv.user.params.key = value
conv.home.params.key = value
Cómo solicitar JSON
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "session_id",
"params": {
"key": "value"
},
"typeOverrides": [],
"languageCode": ""
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED",
"key": "value"
}
},
"home": {
"params": {
"key": "value"
}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Respuesta JSON
{
"session": {
"id": "session_id",
"params": {
"key": "value"
}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "Hello world.",
"text": ""
}
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED",
"key": "value"
}
},
"home": {
"params": {
"key": "value"
}
}
}
Verifica las capacidades del dispositivo
Puedes verificar las capacidades de un dispositivo para ofrecer diferentes experiencias o flujos de conversación.
Node.js
const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsLongFormAudio = conv.device.capabilities.includes("LONG_FORM_AUDIO");
const supportsSpeech = conv.device.capabilities.includes("SPEECH");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");
Cómo solicitar JSON
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "session_id",
"params": {},
"typeOverrides": [],
"languageCode": ""
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO",
"INTERACTIVE_CANVAS"
]
}
}
Para obtener una lista completa de las funciones de la plataforma, consulta la referencia de Capability.
Anulaciones del tipo de entorno de ejecución
Los tipos de entorno de ejecución te permiten modificar las especificaciones de tipos en el entorno de ejecución. Puedes usar esta función para cargar datos de otras fuentes a fin de propagar valores válidos de un tipo. Por ejemplo, puedes usar anulaciones del tipo de entorno de ejecución para agregar opciones dinámicas a una pregunta de la encuesta o para agregar un elemento diario a un menú.
Para usar tipos de entorno de ejecución, debes activar un webhook desde la acción que llama a un controlador en la entrega. Desde allí, puedes propagar el parámetro session.typeOverrides en una respuesta a tu acción. Los modos disponibles incluyen TYPE_MERGE para conservar las entradas de tipo existentes o TYPE_REPLACE a fin de reemplazar entradas existentes con las anulaciones.
Node.js
conv.session.typeOverrides = [{
name: type_name,
mode: 'TYPE_REPLACE',
synonym: {
entries: [
{
name: 'ITEM_1',
synonyms: ['Item 1', 'First item']
},
{
name: 'ITEM_2',
synonyms: ['Item 2', 'Second item']
},
{
name: 'ITEM_3',
synonyms: ['Item 3', 'Third item']
},
{
name: 'ITEM_4',
synonyms: ['Item 4', 'Fourth item']
},
]
}
}];
Respuesta JSON
{
"session": {
"id": "session_id",
"params": {},
"typeOverrides": [
{
"name": "type_name",
"synonym": {
"entries": [
{
"name": "ITEM_1",
"synonyms": [
"Item 1",
"First item"
]
},
{
"name": "ITEM_2",
"synonyms": [
"Item 2",
"Second item"
]
},
{
"name": "ITEM_3",
"synonyms": [
"Item 3",
"Third item"
]
},
{
"name": "ITEM_4",
"synonyms": [
"Item 4",
"Fourth item"
]
}
]
},
"typeOverrideMode": "TYPE_REPLACE"
}
]
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": "This is an example prompt."
}
}
}
Proporcionar personalización de voz
La personalización de la voz le permite especificar sugerencias a la CLN para mejorar la coincidencia de intents. Puedes especificar hasta 1,000 entradas.
Node.js
conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'
Respuesta JSON
{
"session": {
"id": "session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": "This is an example prompt."
}
},
"expected": {
"speech": "['value_1', 'value_2']",
"language": "locale_string"
}
}
Escenas de transición
Además de definir las transiciones estáticas en tu proyecto de acciones, puedes hacer que ocurran transiciones de escena durante el tiempo de ejecución.
Node.js
app.handle('transition_to_hidden_scene', conv => {
// Dynamic transition
conv.scene.next.name = "HiddenScene";
});
Respuesta JSON
{
"session": {
"id": "session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {},
"next": {
"name": "HiddenScene"
}
}
}
Leer ranuras
Durante el llenado de ranuras, puedes usar la entrega para validar la ranura o verificar el estado del relleno (SlotFillingStatus).
Node.js
conv.scene.slotFillingStatus // FINAL means all slots are filled
conv.scene.slots // Object that contains all the slots
conv.scene.slots['slot_name'].<property_name> // Accessing a specific slot's properties
Por ejemplo, supongamos que desea extraer la zona horaria de una respuesta. En este ejemplo, el nombre del espacio es datetime1. Para obtener la zona horaria, debes usar lo siguiente:
conv.scene.slots['datetime1'].value.time_zone.id
Cómo solicitar JSON
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "",
"params": {
"slot_name": {
"original": "1",
"resolved": 1
}
},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "FINAL",
"slots": {
"slot_name": {
"mode": "REQUIRED",
"status": "SLOT_UNSPECIFIED",
"updated": true,
"value": 1
}
},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
},
"session": {
"id": "session_id",
"params": {
"slot_name": 1
},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
}
},
"home": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Invalida ranuras de escena
Puedes invalidar ranuras y hacer que el usuario proporcione un valor nuevo.
Node.js
conv.scene.slots['slot_name'].status = 'INVALID'
Respuesta JSON
{
"session": {
"id": "session_id",
"params": {
"slot_name": 1
}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {
"slot_name": {
"mode": "REQUIRED",
"status": "INVALID",
"updated": true,
"value": 1
}
},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
}
}
Opciones de desarrollo
Actions Builder proporciona un editor directo llamado editor de Cloud Functions, que te permite crear e implementar una Cloud Function para Firebase directamente en la consola. También puedes compilar y, luego, implementar la entrega en el hosting que elijas y registrar el extremo de entrega de HTTPS como tu controlador de webhook.
Editor directo
Para desarrollar con el editor de Cloud Functions, sigue estos pasos:
- Abre tu proyecto de acciones y ve a la pestaña Desarrollo > Webhook > Cambiar método de entrega. Aparecerá la ventana Fulfillment method.
- Selecciona Cloud Functions intercaladas y haz clic en Confirmar.
Extremo HTTPS externo
En esta sección, se describe cómo configurar Cloud Functions para Firebase como servicio de entrega para la acción de conversación. Sin embargo, puedes implementar la entrega en un servicio de hosting de tu elección.
Cómo configurar el entorno
Para configurar tu entorno, sigue estos pasos:
- Descarga y, luego, instala Node.js.
Configura y, luego, inicializa Firebase CLI. Si el siguiente comando falla con un error
EACCES, es posible que debas cambiar los permisos de npm.npm install -g firebase-toolsAutentica la herramienta de Firebase con tu Cuenta de Google:
firebase loginInicia el directorio del proyecto en el que guardaste tu proyecto de Actions. Se te pedirá que selecciones las funciones de Firebase CLI que deseas configurar para el proyecto de Actions. Elige
Functionsy otras funciones que tal vez quieras usar, como Firestore; luego, presiona Intro para confirmar y continuar:$ cd <ACTIONS_PROJECT_DIRECTORY> $ firebase initSelecciona la herramienta Firebase con tu proyecto de Actions mediante las teclas de flecha para asociarla con la lista de proyectos.
Después de elegir el proyecto, la herramienta de Firebase inicia la configuración de Functions y te pregunta qué idioma quieres usar. Selecciona con las teclas de flecha y presiona Intro para continuar.
=== Functions Setup A functions directory will be created in your project with a Node.js package pre-configured. Functions can be deployed with firebase deploy. ? What language would you like to use to write Cloud Functions? (Use arrow keys) > JavaScript TypeScript
Para elegir si deseas usar ESLint para detectar posibles errores y aplicar el estilo, escribe Y o N:
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
Para obtener las dependencias del proyecto, escriba Y en el mensaje:
? Do you want to install dependencies with npm now? (Y/n)
Una vez completada la configuración, verás un resultado similar al siguiente:
✔ Firebase initialization complete!Instala la dependencia @assistant/Conversation:
$ cd <ACTIONS_PROJECT_DIRECTORY>/functions $ npm install @assistant/conversation --saveObtén las dependencias de entrega y, luego, implementa la función de entrega:
$ npm install $ firebase deploy --only functionsLa implementación tarda unos minutos. Cuando termines, verás un resultado similar al siguiente. Necesitas la URL de función para ingresar en Dialogflow.
✔ Deploy complete!
Project Console: https://console.firebase.google.com/project/<PROJECT_ID>/overview Function URL (<FUNCTION_NAME>): https://us-central1-<PROJECT_ID>.cloudfunctions.net/<FUNCTION_NAME>Copia la URL de entrega que se usará en la siguiente sección.
Registra el controlador de webhook
Para registrar tu extremo de Cloud Function como un controlador de webhook, haz lo siguiente:
- En la Consola de Actions, haz clic en Develop > Webhook.
- Haz clic en Cambiar método de entrega. Aparecerá la ventana Fulfillment method.
- Selecciona Webhook y haz clic en Confirmar.
- Pega la URL del servicio web en el campo Webhook.
- Haz clic en Guardar.