Webservice

Estructura

• id: Número de identificación del webservice. Debe ser del tipo string.

• type: Tipo de elemento. Debe ser del tipo string.

• mapping: Es la relación entre la respuesta del webservice y las variables donde se almacenarán los datos de dicha respuesta.

{
    "id": "11304c7d3c63528329a3f48da841b69d3f83991c",
    "type": "webservice",
    "mapping": {
        "msisdn": "@msisdn",
        "orderID": "@order_id",
        "fullName": "@full_name",
        "contractID": "@contract_id"
    }
}

Los steps solo admiten un elemento de tipo webservice por acción. Es decir, cada elemento de tipo webservice tiene que tener su propio step.

Alta de un webservice

Para dar de alta un webservice se deberá acceder al formulario utilizando los botones disponibles en el menú principal y completarlo con todos los datos requeridos. Una vez hecho esto el webservice estará listo para ser usado en los bots.

Formulario de alta de webservice

Uso de variables en un webservice

Es posible utilizar variables guardadas en steps previos dentro de un webservice, tanto en la URL como en el body de la petición.

Supongamos que en el step de bienvenida solicitamos el usuario que nos ingrese su número de identificación de usuario y lo almacenamos en la variable @user_id. Esta variable se podrá utilizar en cualquier parte del bot, incluido el webservice.

Se puede reemplazar variables en la URL de la siguiente forma:

Variables en URL

O reemplazar variables en el body de la petición:

Variables en el body

Mapping y guardado de variables

Este elemento permite obtener datos desde un webservice y almacenar valores en variables que estarán disponibles en cualquier punto del bot.

Para esto será necesario colocar la respuesta del webservice como clave y el nombre de la variable como valor. En el ejemplo se puede ver que de los datos que devuelve el webservice se desea guardar el contractID, orderID, fullName y msisdn.

Respuesta del webservice

{
  "code": "0",
  "contractID": "A000000",
  "orderID": "12345678",
  "fullName": "Pedro",
  "msisdn": "0"
}

Mapping en el flujo del bot

"mapping": {
    "msisdn": "@msisdn",
    "orderID": "@order_id",
    "fullName": "@full_name",
    "contractID": "@contract_id"
}

La estructura de la respuesta del webservice tiene que coincidir con la estructura indicada en el mapping.

En el siguiente ejemplo el webservice nos devuelve el valor document_num dentro del body de la respuesta por lo que tendremos que respetar esta estructura al momento de realizar el mapping.

Respuesta del webservice

{
  "body": {
    "document_num": "998T"
  },
  "code": 0,
  "message": "done"
}

Mapping en el flujo del bot

"mapping": {
    "body": {
        "document_num": "@dni_number"
    }
}

Next step

El campo next_step es indispensable para el flujo del bot, en el caso de los elementos del tipo input, quickReplies, buttonMessage, carousel y webservice puede ser del tipo string o un array de strings con condicionales.

Si solo se indica un string el bot irá al próximo step sin importar el botón que se haya pulsado

"next_step": "your_step_name_here"

En cambio, es posible variar el flujo del bot dependiendo de la interacción del usuario. Para esto es necesario declarar el valor del next_step como un array de strings de uno o mas elementos. La estructura del condicional debe ser: if nombre_de_la_variable == 'valor_a_comparar' : return nombre_del_step.

"next_step" : [
                "if @dni_number == '998T': return welcome_step", 
                "if @dni_number != '998T': return user_error_step", 
                ]

Las condiciones lógicas admitidas son:

• == : Igual a

• != : Distinto a

• and == Y

• or == O

Si el valor a comparar es un string se deberán incluir comillas simples

if nombre_de_la_variable == 'valor_a_comparar_string' : return nombre_del_step

En cambio si el valor a comparar es un integer NO se deberán incluir comillas simples

if nombre_de_la_variable == 10 : return nombre_del_step

En el caso de los webservices también podemos indicar el next_step en base a la respuesta obtenida como se ve en el siguiente ejemplo.

Este webservice revisa que las entradas que solicita un usuario estén disponibles, no estén disponibles o que ya exista una reserva previa por parte de este usuario. Almacenamos el valor de "code" de la respuesta en una variable de nombre @reservation_status_code y la evaluamos para obtener el next_step.

{
    "name": "confirm_ticket_availability",
    "tags": null,
    "actions": [
        {
            "id": "4bbafd3b4326d778cfb9c1de00a2b2f555d4abf3",
            "type": "webservice",
            "mapping": {
                "body": {
                    "summary": {
                        "fila": "@reservation_row",
                        "zona": "@reservation_zone",
                        "puerta": "@reservation_gate",
                        "butacas": "@reservation_seat"
                    },
                    "reserved": "@reserved",
                    "reserve_id": "@reservation_id"
                },
                "code": "@reservation_status_code"
            }
        }
    ],
    "next_step": [
        "if @reservation_status_code == 0: return ticket_available",
        "if @reservation_status_code == 7: return ticket_not_available",
        "if @reservation_status_code == 6: return ticket_already_taken"
    ],
    "variables": {}
}

Ejemplo de uso en un bot

Para insertar un webservice en el flujo del bot se deberá seleccionar el elemento desde el menú desplegable. En este menú estarán todos los webservice dados de alta por el usuario.

Una vez seleccionado se mostrara un step base con un elemento del tipo webservice y el id correspondiente. Solo se deberá copiar ese código y pegarlo en el json del flujo del bot, allí se podrá editar el nombre del step, el mapping y el next_step.