Integración con APIs de terceros

Puedes crear bots que interactúen con otros recursos mediante API. Por ejemplo, los bots pueden procesar solicitudes para verificar si es posible agendar una cita en una fecha determinada o buscar un producto en una tienda en línea.

Cómo manejar una API de terceros con el ejemplo de DaData

Tomemos como ejemplo las sugerencias de API de https://dadata.ru/api/suggest/address

Lee atentamente la documentación de las APIs de terceros

Abre tu proyecto en Mavibot y ve a la configuración avanzada de un bloque; allí debes cambiar el tipo de solicitud a POST-json.

En el campo “URL de solicitud” ingresa la siguiente URL: https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address

En el campo “Encabezado de solicitud” escribe el encabezado en formato JSON:

{ "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }

En los “Parámetros JSON” coloca la solicitud en sí: { "query": "#{CurrencyType}" }

Para obtener los resultados también deberás completar la pestaña “Valores almacenados”.

Un ejemplo de la solicitud está a continuación:

Cómo guardar valores desde variables

No todos lo entienden de inmediato, hasta que lo intentas por ti mismo.

Para empezar, escribe #{custom_answer} en el campo de respuesta. (La variable #{custom_answer} contiene la respuesta obtenida del servidor que se mencionó en el campo “URL para una respuesta del servidor”)

Ejecuta el bloque con la solicitud para enviar la petición y obtener una respuesta. Debes analizar la respuesta y configurar el acceso a las variables en ella. Para esto, necesitas trabajar con la pestaña “Valores almacenados”.

Veamos un ejemplo para entender mejor el proceso.

Como resultado de nuestra solicitud #{custom_answer}, llegó una respuesta con el formato:

{"suggestions": [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]}

Ahora escribamos en el campo “Valores almacenados” nuestro VALOR->VARIABLE

suggestions - la clave del array [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]

suggestions|0 - la clave del primer elemento en el array {"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}

suggestions|0|value - la clave para el valor “British pound”

La clave más larga en este JSON:

suggestions|0|data|strcode - la clave para el valor “GBP”

Las claves se separan con la línea vertical (|). Si hay un array en JSON, entonces el acceso a su elemento se numera comenzando desde el 0 y también se escribe con la línea vertical.

Es necesario repetir todo el anidamiento. Para mayor comodidad, puedes visualizar JSON en una aplicación JSON-viewer.

Los niveles de anidamiento se separan con líneas verticales. Por lo tanto, debes listar todas las claves separadas por la línea para llegar al valor.

Si hay un array en JSON, entonces en lugar de la clave debes mencionar el número del elemento comenzando desde 0.

Separa las frases de obtención de variables con el símbolo de punto y coma (;). Las frases consisten en el enlace a los datos en la respuesta y el nombre de la variable para guardarlos, separados por los símbolos -> (guión + corchete angular).

La consulta de búsqueda es, en cierto modo, una ruta en JSON hacia el valor necesario.

Desarrollo de API para bots

Para desarrollar una API, necesitarás un hosting donde se aloje. Si no tienes uno o no eres un experto en programación, puedes contactarnos y desarrollaremos la API para tu bot y la alojaremos en el nuestro. El hosting en sí es gratuito, solo pagarás por el desarrollo.

Pero por ahora, un poco de teoría.

El bot soporta las solicitudes GET y POST, que son los tipos principales utilizados en la mayoría de las APIs públicas.

GET es una solicitud que ocurre al hacer clic en un enlace o al abrir un enlace en el navegador. Los parámetros en dicha solicitud se transfieren en la URL.

La sintaxis de los parámetros transferidos: después de la URL hay un signo de interrogación (?), luego cada parámetro se separa con el ampersand (&). Un parámetro consiste en el nombre y su valor después del signo igual (=). Un ejemplo de una URL con un parámetro:

Aquí puedes ver que se comparte un parámetro llamado “search_query” y que su valor es “queen live aid”. El ‘+’ aquí es el espacio entre las palabras; al trabajar con el software de edición puedes simplemente dejar los espacios – el bot lo cambiará por sí mismo.

POST es un tipo de solicitud que se envía con mayor frecuencia al completar un formulario en un sitio web. La solicitud transfiere los parámetros en el cuerpo; por supuesto, se pueden compartir de la misma manera que GET, pero rara vez se hace así. El parámetro en el cuerpo puede estar en formato JSON o como clave-valor. Como clave-valor, los parámetros comparten formularios; el formato JSON es el que se usa más a menudo para API.

Encabezado de solicitud. Cada solicitud puede tener un encabezado/título añadido. En él se escribe con mayor frecuencia el formato de los datos compartidos y las claves de acceso. Normalmente dejamos esta pestaña vacía, pero es necesario poner el Token de API o el tipo de solicitud “Content-type”: “application/json” en raras ocasiones.

JSON - (JavaScript Object Notation) es un formato de archivo estándar abierto y un formato de intercambio de datos que utiliza texto legible por humanos para almacenar y transmitir objetos de datos que consisten en pares atributo-valor y arrays. Para trabajar con la API en bots, debes conocer este formato, todo se basa en él.

Antes de continuar, lee los siguientes artículos:

https://www.json.org/json-en.html
https://developer.mozilla.org/en-US/docs/learn/javascript/objects/json

Y también intenta crear tu propio archivo JSON en este sitio:

https://jsoneditoronline.org

Práctica

Los bloques y las condiciones pueden procesar solicitudes. Las solicitudes de condición se crean para entender en el sitio si el diálogo puede seguir un camino determinado o no. La solicitud en este caso ocurre cada vez que se verifica la condición del camino. Las solicitudes de los bloques, por el contrario, solo se ejecutan cuando ocurre el movimiento hacia el bloque.

Antes de crear una solicitud, debes elegir su tipo:

POST-data y POST-json se diferencian por el método de transferencia de parámetros como se mencionó anteriormente (formato JSON o como clave-valor). Si eliges JSON, los parámetros solo se pueden transferir en la solicitud. Se abre un campo adicional para el post: Parámetros JSON POST. ¡Importante! Los parámetros deben escribirse solo en formato JSON, el bot solo funciona así.

La respuesta del servidor se puede analizar y guardar en las variables.

Solo puedes descifrar la respuesta si está en formato JSON.

Las variables guardadas se escriben en la última entrega no completada; si la entrega se transfiere a través de un bloque rojo, las variables se anulan. Por lo tanto, si necesitas guardar los datos, debes transferir las variables a través del bloque amarillo.

Por cierto, puedes ver lo que el bot ha escrito en las variables en la sección Leads:

Transferencia de datos no como una línea

Por defecto, el valor de la variable viene en el formato #{} pero luego se presenta como una línea. Para que la variable se transfiera como un número, debes desactivar la verificación del formato de los parámetros post-json.

Luego puedes simplemente mencionar el nombre de la variable, como {"key": #{variable_name}}, variable_name es la variable, así que sin usar corchetes.

Después de configurar los parámetros, se recomienda volver a activar la verificación.