Integraciones REST

Conectar Audara con las APIs de tus propios servicios

Vista general del módulo

El módulo API Rest permite integrar Audara con servicios externos por medio de sus APIs: defines la URL del servicio, cómo autenticarte y las solicitudes que quieres ejecutar, y esas solicitudes quedan disponibles para tus flujos de chatbot y voicebot. Lo encuentras en Configuración > General > Integraciones, en la tarjeta API.

• 1  Abre la tarjeta API para ver la lista de integraciones REST. La tarjeta muestra cuántas integraciones tienes configuradas.

• 1  Crea una nueva integración con el botón (+) del encabezado.
• 2  Abre el menú de más opciones (⋮) de cada integración para editarla, desactivarla o eliminarla.

La lista muestra el Nombre de cada integración y su Estado (activo o inactivo). Haz clic en el nombre para abrirla y editarla.

Crear una integración

Presiona el botón (+) en el encabezado de la lista. La configuración se organiza en tres pestañas: Ajustes, Solicitudes y Autenticación. Los campos obligatorios están marcados con un asterisco (*). Al completarlos se activa el botón Guardar.

• 1  Campos de identificación de la integración.
• 2  URL a la que apuntan todas las solicitudes de esta integración.
• 3  Guarda la integración cuando completes los campos obligatorios.

Nombre*

Nombre de la integración. Es el que verás al usarla desde otros módulos.

URL Base*

URL base para las peticiones REST de esta integración. La ruta de cada solicitud se agrega a esta URL.

Variables Globales

En la misma pestaña Ajustes defines las variables globales que se usarán en tus solicitudes, como tokens de autenticación o claves API. Defines el valor una sola vez y lo reutilizas en los headers de la integración.

• 1  Nombre con el que identificas la variable.
• 2  Valor de la variable. Si es secreta, se muestra oculto.
• 3  Interruptor Secreto para proteger el valor.
• 4  Agrega otra variable con el botón (+).

Nombre*

Nombre de la variable. No puede repetirse dentro de la integración.

Valor*

Valor de la variable, por ejemplo el token o la clave que entrega el servicio externo.

Secreto

Si la variable es secreta, su valor se oculta al editar la integración y en los logs.

Headers predeterminados

Aquí defines los headers que se enviarán en todas las solicitudes de la integración, como los headers Authorization o Bearer.

• 1  Key del header, por ejemplo Authorization.
• 2  Variable global que se usará como valor del header.
• 3  Alterna entre usar una variable global y un valor fijo con el ícono junto al campo.

El valor de un header puede venir de dos fuentes:

Variable*

Usa una de las variables globales definidas en Ajustes. Ideal para tokens y claves que quieres reutilizar.

Valor fijo*

Usa un valor estático, como "application/json" o un número de versión. En este modo aparece su propio interruptor Secreto por si el valor fijo también debe ocultarse.

Autenticación

En la pestaña Autenticación configuras cómo la integración se autentica con el servicio externo. Úsala para APIs que requieren OAuth 2.0.

• 1  Tipo de autenticación de la integración.
• 2  Endpoint que emite el token, según el proveedor.
• 3  Dónde se envían las credenciales al pedir el token.

Tipo de autenticación

Selecciona Ninguna para usar solo headers estáticos, Bearer Token para un token fijo, u OAuth 2.0 (Client Credentials) para obtener y renovar un token automáticamente.

Bearer Token

Token*

Token que se enviará como header "Authorization: Bearer" en todas las solicitudes. Se almacena de forma segura y se oculta al editar.

OAuth 2.0 (Client Credentials)

Token URL*

Endpoint que emite el token. Para Microsoft tiene la forma https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token.

Client ID*

Identificador de la aplicación registrada en el proveedor.

Client Secret*

Secreto de la aplicación. Se almacena de forma segura y se oculta al editar.

Scope

Alcance del token. Para Dynamics tiene la forma https://<org>.crm.dynamics.com/.default.

Ubicación de las credenciales

Dónde se envían el Client ID y el Secret en la petición del token. La mayoría de proveedores los recibe en el cuerpo; algunos requieren un header Basic.

Parámetros adicionales

Parámetros extra para la petición del token, por ejemplo "resource" o "audience" según el proveedor. Cada uno se define como clave y valor.

Solicitudes

En la pestaña Solicitudes defines las peticiones que se usarán desde tus integraciones, como GET o POST. Cada solicitud queda guardada en la integración y lista para usarse desde tus bots.

• 1  Crea una solicitud con el botón Nueva solicitud.
• 2  Haz clic en el nombre de una solicitud para editarla.

Al crear o editar una solicitud se abre el formulario junto al panel Probar solicitud:

• 1  Nombre de la solicitud.
• 2  Método HTTP.
• 3  Ruta que se agrega a la URL Base.
• 4  Ejecuta la solicitud de prueba con el botón Probar.

Nombre*

Nombre de la solicitud. No puede repetirse dentro de la integración.

Método*

Método HTTP de la solicitud: GET, POST, PUT o PATCH. Cada uno tiene su color en la lista de solicitudes, para reconocerlos de un vistazo.

Ruta*

Ruta de la solicitud. Se agrega a la URL Base de la integración y puede incluir parámetros.

Body JSON*

Body de la solicitud para los métodos que lo envían. Debe ser un JSON válido.

Enviar como

Formato para enviar el body: JSON o Form-data.

Cuando la solicitud envía datos, es decir con POST, PUT o PATCH, el formulario muestra además el formato de envío y el body. Con GET esos dos campos no aparecen.

• 1  Elige el formato de envío del body: JSON o Form-data.
• 2  Escribe el body de la solicitud. Puedes usar variables entre llaves, como {nombre} o {edad}, para llenarlas con datos de la conversación al ejecutar la solicitud desde un bot.
• 3  El panel Probar detecta las variables del body y te pide un valor de prueba para cada una.

Mandar un archivo a tu API

Cuando un chatbot le pide un archivo a la persona, ese archivo se puede guardar en una variable y mandárselo después a tu servicio desde una de estas solicitudes. Del lado del bot, el paso que lo pide es el de captura de archivo, y ahí se elige en qué variable queda guardado; del lado de la integración no tienes que configurar nada especial, solo usar esa variable en el body como cualquier otra.

• 1  El método. Muchos servicios de subida usan PUT.
• 2  Enviar como decide si sube el archivo o un enlace a él.
• 3  La variable del archivo va en el body como cualquier otra, entre llaves.
• 4  En el panel Probar, el método se muestra con su color.

Lo que decide la solicitud es cómo viaja el archivo, y eso sale del campo Enviar como:

Form-data

El archivo viaja dentro de la petición, como cuando lo subes desde un formulario web. Es lo que espera la mayoría de servicios que reciben archivos.

JSON

En lugar del archivo viaja un enlace para descargarlo, que vive una hora. Tu servicio recibe la dirección y baja el archivo por su cuenta dentro de ese plazo.

No hay una tercera opción, y no te toca coordinar las dos puntas: eliges el formato y Audara arma la petición que corresponde.

Probar y elegir campos de la respuesta

El panel Probar solicitud muestra el método y la URL completa que se va a ejecutar. Presiona Probar para enviar la solicitud real al servicio y ver la respuesta.

• 1  Ejecuta la prueba con el botón Probar.
• 2  El Status indica el resultado de la petición.
• 3  Haz clic en los campos resaltados de la respuesta para seleccionarlos como variables.
• 4  Los campos seleccionados aparecen en Campos respuesta.

Los campos que selecciones son los que quedan disponibles como variables al usar la solicitud desde otros módulos. En Campos respuesta puedes cambiarles el nombre por uno más informativo; si dejas el campo vacío, conserva el nombre original de la respuesta.

Respuestas tipo lista

Cuando la respuesta trae un arreglo de elementos, por ejemplo una lista de contactos o de citas disponibles, puedes tratar todo el arreglo como una sola variable de tipo lista.

• 1  Presiona el ícono de lista junto al arreglo para tratarlo como lista. La respuesta se contrae y muestra solo el primer elemento como muestra.
• 2  Nombre de la variable que contendrá la lista.
• 3  Plantilla con la que se muestra cada elemento.
• 4  Texto que separa los elementos al unir la lista.

Nombre de la variable

Nombre con el que usarás la lista completa desde otros módulos.

Campos del elemento

Campos de cada elemento que quieres usar. Selecciónalos haciendo clic en los campos resaltados dentro del elemento de muestra, y renómbralos si necesitas nombres más claros.

Plantilla del elemento (opcional)

Cómo se muestra cada elemento. Inserta valores con {NombreCampo}, usando el nombre que le diste al campo, o con la ruta directa como {name.first}. Por ejemplo: {Nombre} <{email}>. Si la dejas vacía, se unen los campos seleccionados separados por espacio.

Separador

Texto que se coloca entre cada elemento al unir la lista. Por defecto es una coma con espacio, y el botón Nueva línea usa un salto de línea.

Dónde se usan las integraciones

Las solicitudes que configures quedan disponibles en los flujos de tus bots:

• Chatbots: el paso de integración ejecuta una solicitud, le envía variables de la conversación y guarda los campos de la respuesta como variables del chat, listas para usarse en los mensajes y condiciones siguientes.
• Voicebots: los flujos de voz ejecutan las mismas solicitudes y usan los campos de la respuesta dentro de la llamada.

En ambos casos, los campos y listas que definiste en Campos respuesta son los que aparecen como variables disponibles.

Editar, desactivar o eliminar

Haz clic en el nombre de una integración para editarla. Desde el menú de más opciones (⋮) a la derecha de cada integración puedes Editar, Desactivar o Eliminar. Una integración desactivada conserva su configuración pero deja de estar disponible.