Referencia de la API de Interactive Canvas

La API de Interactive Canvas es una biblioteca de JavaScript que puedes usar para interactuar con tu acción de conversación mediante el objeto interactiveCanvas en tu aplicación web.

Nota: El objeto interactiveCanvas se adjunta al objeto window. Si usas un framework de frontend para desarrollar tu aplicación web, debes asegurarte de tener acceso a window a fin de configurar la API.

Para obtener más información sobre Interactive Canvas, consulta la documentación de Interactive Canvas.

Métodos

Advertencia: Algunas de las API de Interactive Canvas se encuentran actualmente en la Vista previa para desarrolladores. Puedes probar las APIs en el simulador, pero no implementes una acción que use estas funciones en los canales alfa, beta o de producción. Las acciones implementadas con estas funciones no funcionarán en los dispositivos del usuario final.

lista

ready(callbacks) returns undefined

La app web de Interactive Canvas la llama una vez que se carga para registrar devoluciones de llamada.

Parámetros
callbacks	InteractiveCanvasCallbacks Un objeto que contiene devoluciones de llamada de métodos.

Nota: Debes invocar la API de ready en la aplicación web en cuanto se cargue la página. De lo contrario, la acción se cierra.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Envía una consulta de texto a la acción de conversación.

Parámetros
textQuery	string La consulta que se enviará a la acción de conversación.
state	string Uno de los siguientes: READY: La plataforma puede aceptar las solicitudes. BLOCKED: Hay una consulta en curso y se descartará la consulta nueva. UNKNOWN: No se pudo determinar el estado actual de la consulta.

Precaución: textQuery debe tener 640 caracteres o menos.

getHeaderHeightPx.

getHeaderHeightPx() returns Promise<height>

Determina la altura del encabezado en la parte superior de una pantalla.

Parámetros
height	number La altura en píxeles.

TTS de salida

outputTts(text, openMic) returns undefined;

Reproduce texto de SSML.

Parámetros
text	string Es la string compatible con SSML que se reproducirá.
openMic	boolean Si se debe activar el micrófono después de que se reproduzca el TTS.

createIntentHandler

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

createIntentHandler(intentId, callback) returns IntentHandler

Crea un controlador de intents para un intent personalizado de CLN.

Parámetros
intentId	string Nombre del intent, como se define en Actions Builder.
callback	function(MatchedIntent) Es la función que se ejecutará cuando se detecte la coincidencia con el intent.
IntentHandler	object Objeto del controlador de intents que se puede registrar con expect().

Controlador de intent

Es un objeto que representa un controlador de intents. Se puede registrar con expect() o prompt().

Intent de coincidencia

Es un objeto que contiene los datos de un intent coincidente.

Métodos
getIntentArg(parameterName)	function(string) Es el método para obtener el parámetro de intent de un intent coincidente.

CrearNúmeroRanura

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

createNumberSlot(callback, hints?) returns Slot<number>

Crea una ranura de tipo número.

Parámetros
callback	function(FilledSlot) Es la función que se ejecutará cuando se ocupe la ranura.
hints	Hints Palabras cortas que el usuario podría decir al llenar un espacio. hints ayuda al sistema de CLN a decidir qué ranura llenar.
Slot	object Objeto de ranura que se puede registrar con prompt().

CrearTextoRanura

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

createTextSlot(callback, hints?) returns Slot<string>

Crea una ranura de tipo string.

Parámetros
callback	function(FilledSlot) Es la función que se ejecutará cuando se ocupe la ranura.
hints	Hints Palabras cortas que el usuario podría decir al llenar un espacio. hints ayuda al sistema de CLN a decidir qué ranura llenar.
Slot	object Objeto de ranura que se puede registrar con prompt().

createConfirmationSlot

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

createConfirmationSlot(callback, hints?) returns Slot<boolean>

Crea una ranura de tipo booleano.

Parámetros
callback	function(FilledSlot) Es la función que se ejecutará cuando se ocupe la ranura.
hints	Hints Palabras cortas que el usuario podría decir al llenar un espacio. hints ayuda al sistema de CLN a decidir qué ranura llenar.
Slot	object Objeto de ranura que se puede registrar con prompt().

CrearOpciones

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

createOptionsSlot(options, callback, hints?) returns Slot<string>

Crea un espacio a partir de una lista predefinida de opciones.

Parámetros
options	array<Option> Es la función que se ejecutará cuando se ocupe la ranura.
callback	function(FilledSlot) Es la función que se ejecutará cuando se ocupe la ranura.
hints	Hints Palabras cortas que el usuario podría decir al llenar un espacio. hints ayuda al sistema de CLN a decidir qué ranura llenar.
Slot	object Objeto de ranura que se puede registrar con prompt().

Ranura

Un objeto que representa un espacio para llenar. Se puede registrar con expect() o prompt().

Ranura rellenada<T>

Es un objeto que representa un espacio lleno.

Parámetro
T	boolean|number|string El tipo de ranura

Opción

Es un objeto que representa una entrada de tipo de ranura.

Campos
key	string Es el identificador único de la entrada del tipo de ranura.
synonyms	array<string> Es una lista de palabras que se usa para seleccionar la opción de ranura.

Sugerencias

Es un objeto que representa sugerencias de un espacio.

Campos
associatedWords	array<string> Es una lista de palabras que se usa para ayudar al sistema de CLN a decidir qué espacio debe llenar.

Espera

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

expect(expectation) returns HandlerRegistration

Registra la expectativa del cliente. Se puede llamar en controladores de ranuras y ranuras para intents.

Parámetros
expectation	IntentHandler|Slot El controlador o la ranura para el intent que se registrará.
HandlerRegistration	object El controlador o la ranura para el intent registrado.

Registro de controladores

Es un objeto que representa un controlador de intents registrado.

Métodos
deleteHandler()	function Cancela el registro del controlador de intents esperado.

ClearExpectations

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

clearExpectations() returns undefined;

Quita todas las expectativas, ya que borra todos los controladores y ranuras de intents que se registraron anteriormente.

mensaje

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

prompt(tts, expectation) returns Promise<Answer<T>>

Avisa al usuario con la string de TTS proporcionada y registra la expectativa en el cliente. Se puede llamar en controladores de ranuras y ranuras para intents.

Parámetros
tts	string Es la string de TTS que se usa para solicitarle al usuario la expectativa proporcionada.
expectation	IntentHandler|Slot El controlador o la ranura para el intent que se registrará.
Answer<T>	object La respuesta que proporcionó el usuario al mensaje.

Respuesta<T>

Es un objeto que representa una respuesta proporcionada por el usuario a un mensaje.

Campos
value	boolean|number|string Es el valor de la respuesta proporcionada por el usuario.
status	string El estado de la respuesta. Uno de los siguientes: ANSWERED: El usuario respondió el mensaje con una respuesta. NO_MATCH: Se le solicitó al usuario una respuesta y respondió con una respuesta que no coincidía con la respuesta esperada o cualquier otro intent esperado. YIELD: El usuario respondió el mensaje con un intent diferente.

Scene_Trigger

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

Activa una escena.

Parámetros
sceneName	string El nombre de la escena que se activará.
TriggerSceneStatus	string El estado de la llamada a triggerScene(). Uno de los siguientes: SUCCESS: El servidor procesó correctamente la solicitud. BLOCKED: Una solicitud existente bloqueó la solicitud. UNKNOWN: Se desconoce el estado de la solicitud.

setUserParam

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

setUserParam(key, value) returns Promise<undefined>;

Establece el par clave-valor que se pasa y conserva entre conversaciones.

Parámetros
key	string La clave del parámetro.
value	object|array|boolean|number|string Es el valor del parámetro.

getUserParam.

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

getUserParam(key) returns Promise<object|array|boolean|number|string>;

Obtiene el valor del parámetro para la clave dada si existe y el estado de la invocación.

Parámetros
key	string La clave del parámetro.

resetUserParam

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

resetUserParam() returns Promise<void>;

Borra todos los parámetros de usuario.

SetHomeParam

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

setHomeParam(key, value) returns Promise<undefined>;

Establece el par clave-valor que se pasa y conserva entre conversaciones.

Parámetros
key	string La clave del parámetro.
value	object|array|boolean|number|string Es el valor del parámetro.

getHomeParam.

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

getHomeParam(key) returns Promise<object|array|boolean|number|string>;

Obtiene el valor del parámetro para la clave dada si existe y el estado de la invocación.

Parámetros
key	string La clave del parámetro.

restablecerHomeParam

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

resetHomeParam() returns Promise<void>;

Borra todos los parámetros de usuario.

setCanvasState

setCanvasState(state) returns undefined

Notifica al Asistente que la app web de Canvas actualizó su estado. El método setCanvasState no muestra un valor. Se puede acceder a la carga útil de estado a través de la propiedad conv.context.canvas.state.

Precaución: La longitud de la representación de string del objeto state debe ser de 50,000 caracteres o menos. Si la string supera los 50,000 caracteres, se genera un error.

Parámetros
state	Object El estado actualizado de la app de Canvas como un objeto JSON.

Devoluciones de llamada de InteractiveCanvas

Estas devoluciones de llamada te permiten responder a la información o solicitudes de tu acción de conversación, mientras que los métodos proporcionan una manera de enviar información o solicitudes a ella.

onActualizar

onUpdate(data) returns Promise|undefined

Se llama cuando se envía una respuesta Canvas de la acción de conversación. TTS comenzará cuando se resuelva la promesa que se muestra o se agote el tiempo de espera después de 10 segundos.

Parámetros
data	Object Datos actualizados enviados por el webhook.

onTtsMark

onTtsMark(markName) returns undefined

Es la devolución de llamada que se invoca durante la reproducción de TTS.

Marcas especiales que siempre se activan:

• START indica el inicio de TTS.
• END: Indica el final de la TTS.
• ERROR: Indica un error al reproducir el TTS.

También puedes definir marcas personalizadas con SSML y la etiqueta <mark>, como <mark name="custom"/>.

Nota: Las marcas de SSML no se invocan cuando ocurre lo siguiente:

• Antes de que comience el TTS, el usuario presiona el micrófono o el cliente de Interactive Canvas invoca a sendTextQuery. Se cancela el TTS y se ignoran todas las marcas de SSML en el TTS.
• Durante la TTS, el usuario presiona el micrófono o el cliente de Interactive Canvas invoca a sendTextQuery. Se interrumpe el TTS y se ignoran las marcas de SSML restantes en el TTS.

Parámetros
markName	string Marca el nombre invocado durante la reproducción de TTS.

onInputStatusChanged

Precaución: Actualmente, esta API se encuentra en la Vista previa para desarrolladores. Puedes probar esta API en el simulador, pero no implementes una acción que use esta función en los canales alfa, beta o de producción. Las acciones implementadas con esta función no funcionarán en dispositivos de usuario final.

onInputStatusChanged(inputStatus) returns undefined

Notifica a la app de Canvas que cambió el estado de entrada de Asistente.

Parámetros
inputStatus	Enum Estado del procesamiento de entrada de voz o texto en el dispositivo. Puede ser la siguiente: LISTENING : El micrófono está activado. IDLE : El micrófono está cerrado. PROCESSING : En este momento, Asistente está ejecutando una consulta (el micrófono está cerrado).