Cómo crear una skill de Alexa conectada con las API de BBVA

Ahora que los asistentes virtuales están en boca de todos vamos a ver lo sencillo que es realizar la integración de servicios de terceros en nuestras propias skills utilizando funciones AWS Lambda desarrolladas en Node.js. Como ejemplo de API, hemos escogido las API públicas que ofrece BBVA en su API Market (por lo estándar de la implementación y la documentación disponible) y en este artículo veremos el proceso de construcción de nuestra skill paso a paso.

El resultado que obtendremos al final será una skill que es capaz de mostrar los datos bancarios del usuario (en este caso del entorno sandbox de BBVA) y que podéis ver cómo se instalaría y utilizaría en el siguiente vídeo:

Lo primero que deberemos hacer es darnos de alta en las siguientes plataformas. Para ello nos dirigiremos a las URLs:

• BBVA API Market
• Amazon Alexa Developer Console
• AWS (Amazon Web Services)

1. Amazon Alexa Developer Consola

Una vez nos hayamos dado de alta en los 3 servicios vamos a proceder a crear una Skill. Para ello vamos al portal de Amazon Alexa Developer Console y a crear una nueva Skill. Pondremos un nombre descriptivo a la Skill y seleccionaremos el idioma asociado.

Una vez creada la skill la dejamos por el momento y procedemos a crear una funciona Lambda en AWS.

2. AWS

Buscamos el servicio Lambda en AWS y damos de alta una nueva función Lambda.

Introducimos nombre, lenguaje en el que vamos a trabajar con la Lambda (en este caso Node 8.10) y rol para los permisos.

NOTA: Las funciones Lambda “Custom” tienen que ser alojadas en una de las siguiente regiones:

• Asia Pacific (Tokyo)
• EU (Ireland)
• US East (N. Virginia)
• US West (Oregon)

Una vez creada la Lambda vamos a aplicar el trigger (desencadenante) de Alexa.

A la izquierda tenemos un listado, haremos click en “Alexa Skill Kit” y se agregará al diagrama y nos mostrará una nueva sección abajo.

Lo siguiente es enlazar nuestra skill de Alexa con nuestra Lambda de AWS.

Para ello nos harán faltan identificadores de ambos servicios. ARN para el caso de la lambda y skill ID para el caso de la skill de Alexa. El ARN de la lambda lo podemos encontrar en la parte superior de la propia pantalla de configuración, el Skill ID se puede consultar en la sección “Endpoint” de la consola de Amazon Alexa. Una vez tengamos los respectivos identificadores vamos primero a la lambda y asignamos el skill ID, guardamos y luego vamos a la pantalla “Endpoint” de nuestra skill e introducimos el ARN de nuestra lambda, guardamos y ya deberíamos tener enlazada nuestra skill con nuestra lambda.

3. BBVA API Market

Para tener acceso a la API de BBVA tendremos que dar de alta una aplicación en la consola. Una vez hecho login, en el dashboard de usuario, podremos crear una aplicación:

PASO 1 — Introducimos nombre de la aplicación, país al que aplica el acceso, entorno de prueba o producción, identificador y descripción de la aplicación.

PASO 2 — En el paso dos, seleccionamos las API a las que queremos acceder, cada una con su endpoint, su scopes y sus necesidades en cuanto a seguridad. Nosotros vamos a pedir acceso a Accounts, para poder ver datos referentes a las cuentas del usuario.

PASO 3 — Por último en el paso tres, tendremos que definir los hosts desde donde accederemos a la API, las URL de redirección para la autenticación, las URL para flujos con autenticación OTP (no usados en este ejemplo) y una URL para términos y condiciones. Esto lo rellenaremos más adelante.

4. Account Linking

Para poder usar datos privados de la plataforma de BBVA con nuestra skill de Alexa tendremos que usar lo que comúnmente se conoce como Account Linking. Con Account Linking el usuario mediante sus credenciales accede a BBVA y permite a nuestra skill de Alexa consultar los servicios de BBVA con un token de acceso, de esta forma podremos recuperar los datos del usuario de BBVA de una forma segura.

En la consola de desarrollo de Amazon Alexa seleccionaremos nuestra skill e iremos al apartado “Account Linking”. Seleccionaremos un flujo de autenticación por código o de 3 pasos, nos saldrán varios campos que tendremos que rellenar, así como las URLs de redirección de Amazon. Esas URL las tenemos que copiar e introducir en el tercer paso de configuración de nuestra app en BBVA API Market.

Así mismo vamos a la página de información de BBVA API Market para introducir las URLs de autenticación y token, así como nuestro client ID y client secret que podemos obtener en el detalle de nuestra app en BBVA API Market.

Una vez hecho los dos pasos anteriores ya tendremos configurado Account Linking en nuestra skill.

Configuración Amazon Alexa Skill

Antes hemos dado de alta una skill de Alexa y configurado parámetros básicos.

El siguiente paso es definir el nombre de invocación de nuestra skill, vamos a “Interaction Model/Invocation” y definimos el nombre que identifique a nuestra skill, en nuestro caso “bbva cuentas”.

Ahora vamos a dar capacidades visuales a nuestra skill, para ello en la sección “Interfaces” activamos la opción “Display Interface”. Veremos que al activar esta opción se crean nuevos intents relacionados con el control de dispositivos con pantalla.

Node + Lambda

Con todo lo anterior configurado vamos a empezar a programar nuestra Lambda.

Lo primero es crear una carpeta para nuestro proyecto, una vez creada nos movemos a la carpeta y ejecutamos el siguiente comando NPM (instrucciones para instalar NPM):

npm init

Esto nos creará un archivo “package.json” con la información que hayamos introducido al ejecutar el comando anterior.

Una vez creado el fichero “package.json” lo abrimos con nuestro editor de texto favorito para indicar las dependencias necesarias para este ejemplo con Alexa. Nos debería quedar un fichero como el siguiente añadiendo la sección de dependencias:

{
 “name”: “skill-name”,
 “version”: “1.0.0”,
 “description”: “”,
 “main”: “index.js”,
 “scripts”: {
 “test”: “echo \”Error: no test specified\” && exit 1"
 },
 “author”: “Daniel J Narbona”,
 “license”: “ISC”,
 “dependencies”: {
 “ask-sdk-core”: “2.0.0”,
 “ask-sdk-model”: “1.0.0”,
 “ask-sdk-v1adapter”: “2.3.0”
 }
}

Una vez configuradas las dependencias vamos a descargar los módulos NPM necesarios con el comando:

npm install

Esto creará una carpeta llamada “node_modules” con las dependencias definidas en el fichero “package.json” y un fichero “package-lock.json”.

Por último crearemos a mano un fichero “index.js” que será sobre el que trabajemos para definir las respuestas a los intents de nuestra skill.

Un buen “index.js” por el que empezar a trabajar puede ser el fichero “index-basic.js” de nuestro repositorio de prueba. Podemos ver que consta de 3 partes principales; las dependencias, los IntentHandlers y la configuración del SkillBuilder de Alexa donde se detallan los distintos handlers que pueden ocuparse de atender los distintos intents de los usuarios.

Ahora lo que vamos a hacer es subir el código anterior a nuestra Lambda, para ello en la consola de AWS abrimos nuestra función y en la sección de “Código de la función” seleccionamos la opción de subir un zip, comprimimos la carpeta anterior y subimos el zip al servicio AWS.

A partir de aquí podemos utilizar el proceso anterior con nuestro editor favorito o editar el código directamente en la web de AWS.

Lo primero que debemos saber es que tal y como esta actualmente configurada la skill ya podemos invocarla en la consola de desarrollo y probar intents y respuestas. De momento el único intent que se va a ejecutar es el intent inicial al lanzar nuestra skill “LaunchRequestHandler”. Ya podemos jugar con la skill y empezar a devolver información relevante para el usuario como por ejemplo qué se puede hacer con nuestra skill. El “LaunchRequestHandler” normalmente se usa para dar la bienvenida al usuario y darle información relevante sobre nuestra skill, así que vamos a hacer la primera prueba con autenticación contra BBVA para poder recuperar información privada del usuario como su nombre.

Test

Para hacer una prueba inicial vamos a la consola de desarrollador de Alexa, seleccionamos la pestaña test e introducimos “abre NOMBRE DE INVOCACIÓN DE NUESTRA SKILL”, si todo ha ido bien deberíamos recibir el output definido en el intent “LaunchRequestHandler”.

El siguiente paso es recuperar el accessToken para poder llamar en nombre del usuario a la API de BBVA, para ello vamos a la consola de Alexa. Vamos a “Skills/Mis Skills/Skills de desarrollador” y seleccionamos nuestra skill. Una vez en el detalle de nuestra skill nos permitirá activarla, al hacer click en este enlace iremos a la página de autenticación de BBVA, introducimos cualquier credencial válida del entorno sandbox, aprobamos los scopes y ¡deberíamos tener nuestra skill enlazada a nuestra cuenta BBVA del entorno sandbox!.

Una vez enlazada la cuenta BBVA con nuestra cuenta Amazon Alexa podemos probar de nuevo, ahora en el JSON Input de la pantalla de test veremos que el objeto usuario lleva también un accessToken que nos permitirá acceder a la API de BBVA.

LaunchRequestHandler

Por lo tanto el siguiente paso es hacer una llamada a la API de BBVA para recuperar la información básica del usuario logado y así poder darle la bienvenida.

Para ello vamos a utilizar el siguiente código, esto no es más que una llamada a la API de BBVA usando Promise de js para ello. Lo que si vamos a detenernos es en las siguientes lineas:

• La obtención del objeto user que nos permite obtener el accessToken provisto por BBVA en el paso anterior en caso de que exista (luego veremos cómo comprobar el estado del usuario con respecto al entorno de BBVA).
• El uso de “Alexa.ImageHelper()” y “Alexa.RichTextContentHelper()” para formatear y enriquecer el contenido.
• Y por último el “responseBuilder” que usaremos para devolver la respuesta que será pintada y hablada por nuestro dispositivo. La mayoría de los métodos de este builder son autoexplicativos; “.speak” indica el texto hablado, “.addRenderTemplateDirective” nos permite definir distintas directivas de visualización por pantalla, “.repromt” que el dispositivo se active de nuevo esperando un comando y “.withSimpleCard” mostrar esa información en la app de Alexa.

var accessToken = handlerInput.requestEnvelope.context.System.user.accessToken;
var speechText;
var image;
var title;
var text;
var options = {
 host: ‘apis.bbva.com’,
 path: ‘/customers-sbx/v1/me-basic’,
 method: ‘GET’,
 headers: { 
‘Authorization’: “jwt “ + accessToken, 
‘Accept’:‘application/json’ }
};
return getData(options).then(function(result) {
  const finalRes = JSON.parse(result);
 
  if (finalRes.result.code == 200) {
    speechText = ‘Bienvenido a BBVA Cuentas. Puedes preguntar acerca del estado de tus cuentas corrientes.’;
    image = new Alexa.ImageHelper().addImageInstance(bbva_building).getImage();
    if (finalRes.data.sex == “FEMALE”) {
      title = “Bienvenida”;
    }
    else {
      title = “Bienvenido”;
    }
    text = new Alexa.RichTextContentHelper().withPrimaryText(finalRes.data.firstName + “ “ + finalRes.data.surname).getTextContent();
    return handlerInput.responseBuilder
     .speak(speechText)
     .addRenderTemplateDirective({
       type: ‘BodyTemplate3’,
       backButton: ‘visible’,
       image,
       title,
       textContent: text
     })
     .reprompt(“”)
     .withSimpleCard(title, speechText)
     .getResponse();
   }
   else {
       …
   }
 },
 function(err) {
     …
 })

Visto lo anterior y ya entrando en materia propia de la skill, cuando usemos skills con Account Linking tendremos que controlar que el accessToken este presente en los intents en que sea necesario, lo podremos controlar con el siguiente código:

if (accessToken == undefined) {
  // The request did not include a token, so tell the user to link
  // accounts and return a LinkAccount card
  speechText = “Debe disponer de una cuenta BBVA para acceder. “ +
  “Por favor use la aplicación de Alexa para autorizar el acceso a su cuenta BBVA”;
  return handlerInput.responseBuilder
   .speak(speechText)
   .withLinkAccountCard()
   .getResponse();
}
else {
  …
}

Con lo anterior ya tenemos una respuesta al evento de inicio de nuestra skill que obtiene datos privados del usuario mediante la API de BBVA API Market y genera una respuesta auditiva y visual.

Ampliar capacidades mediante el uso de intents

El siguiente paso es ampliar la funcionalidad de nuestra skill básica añadiendo un nuevo intent y configurando nuestra lambda para que responda a tal petición.

Accedemos a la consola de desarrollo de Alexa para ir a la sección de intents y crear uno nuevo, lo llamaremos “ShowAccounts” dado que lo que vamos a permitir con este intent es mostrar un listado de nuestras cuentas corrientes y su importe.

Para que Alexa sepa qué esta queriendo decir el usuario tendremos que introducir una seria de “Sample Utterances” o frases de entrenamiento/ejemplo, esto permitirá a Alexa y su NLP saber que el usuario quiere ejecutar este intent cuando diga algo como “muéstrame mis cuentas”.

Una vez que tengamos nuestras frases de prueba introducidas guardamos el intent y nos vamos a nuestra lambda.

Lo primero que haremos será crear un nuevo intent handler al que llamaremos “ShowAccountsIntentHandler”. Una vez creado agregaremos este objeto al “.addRequestHandlers” para que la skill lo tenga en cuenta a la hora de buscar un intent que encaje con la intención del usuario.

Al igual que con el LaunchRequestHandler este objeto tendrá un método “canHandle” que será quién valide si la función handle se debe ejecutar a cierta petición del usuario. Básicamente lo que haremos será usar el siguiente código para comprobar que este código solo se ejecute cuando el usuario quiera información de sus cuentas.

const ShowAccountsIntentHandler = {
  canHandle(handlerInput) {
    return 
handlerInput.requestEnvelope.request.type === ‘IntentRequest’ 
&& 
handlerInput.requestEnvelope.request.intent.name === ‘ShowAccounts’;
  },
  handle(handlerInput) {
    ...
 }
};

De esta forma el código de handle solo se ejecutará si es una request de tipo intent y además el intent especificado por Alexa es “ShowAccounts”, es decir, que el usuario ha indicado una de las frases anteriormente introducidas por nosotros o una muy parecida.

Una vez hemos creado nuestro “ShowAccountsIntentHandler” procedemos a llamar a la API de BBVA, como en el caso anterior, para recuperar información de nuestras cuentas.

Quedando un resultado final como el que podréis encontrar en nuestro repositorio.

NOTA: Este artículo es una guía ilustrativa para crear una skill de Amazon Alexa, no pretende ser ejemplo de buenas prácticas ;)