Introduction

JennyApps allows the integration of JennyBot to external REST APIs. It allows the bot to send information to / fetch information from external REST APIs during conversations. Before proceeding verify with GetJenny that your organisation has Developer actions enabled.

Jenny Studio

To start using JennyApps an organisation must generate a Developers API key. This is done by clicking the user’s name in the Studio and selecting settings.

Under Developer settings the user can generate the API key and find the url for the environment’s Developers API.

After token is created it is found in the developer settings and can be reset to generate replacement. Any token created before Developer actions have been enabled by GetJenny will not work and will have to be reset after actions have been enabled.

Developer API

Once you have the API key it is possible to start creating Developer actions using the API key and Developers API URL. This is done over REST API and all calls must be authenticated by setting the API key in x-api-key header. Developers API has four endpoints:

• GET return list of actions available to the given API key/actions
• POST create new action/actions
• PUT update existing action with id {id}/actions/{id}
• DELETE delete existing action (cannot delete actions currently in use)/actions

Full documentation for payloads and responses as well as example Postman collection available from LeadDesk Support.

Plugin connector

Before the action can be used there must an endpoint to call. The endpoint must be able to receive and return the following format.

Request format

The request body will be a JSON object with two attributes: parameters and query.

• parameters: object containing values of Developer action action input

• query: string containing visitor’s message

{parameters:{ examplevalue: 'Mikkotest' }, query: 'app test' }

Response format

The response should be a JSON object with one mandatory attribute and as many optional variables as wanted. The required attribute is score, this is used to determine if call was successful.

{
    "score": 1,
    "ticket_id": "INC1234"
}

All values will be mapped to data using Developer action ref as prefix.

"data": {
	"example_action.score": "1",
	"example_action.status": "200 OK",
	"example_action.properties": "score, ticket_id",
    "example_action.ticket_id": "INC1234"
}

The response should contain only simple data (Text key - text value pairs).

Example

To create an action that calls endpoint: https://my.app.net/api/createToken with payload

{parameters:{ org: 'example_customer', description:'Issue description'
}, query: 'message }

you can use the following cUrl:

curl -X 'POST' \
'DEVELOPERS API ENDPOINT' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"humanName": "Create ticket",
"hint": "This action creates ticket to org example_customer",
"actionInput": {
"org": "example_customer",
"description": "<<<Description>>>"
},
"params": [
{
"name": "Description",
"hint": "Issue description",
"type": "Text",
"defaultValue":"%description.0%",
"mandatory": true
}
],
"ref": "myorg_create_ticket",
"endpoint": "https://my.app.net/api/createTicket",
"token": "APIKEY"
}'

JennyStudio

Once the action is created it can be assigned to a state in JennyStudio

With the developer actions it is mandatory to setup both a success state and a failure state. Success state is triggered if API call is successful (got score 1) and failure state is returned if API call failed (score 0 or not set at all). It is possible to display data received from the API call using the variable templating. For example in a successful call to create ticket it is possible to display the id of the ticket thusly.

If the ticket is not created it is possible to show the error message like below

Plugin-connector

Both of the cases depend on the endpoint being called returning the values “ticket_id” and “error_message” in case of success and failure.

Response for success

{"score":1, "ticket_id":"INC1234"}

Response for failure

{"score:"0, "error_message":"user not found"}

Below is example NodeJs code for createTicket endpoint

'use strict';
const express = require('express')
const axios = require('axios')
const app = express()
app.use(express.json())

app.post('/api/createTicket', (req, res) => {
    // Get parameters from request body
    let params = req.body.parameters;
    // Get key from authorization header and assign it to headers
    let options = {headers: {'Authorization': req.headers.authorization}}
    // Post to actual endpoint with parameters received from action
    axios.post('https://example-ticketing.com/createTicket', body.params, options).then(response => {
        // Return json with score of 1 and ticket_id from API
        return res.json({"score":1, "ticket":response.data.ticket.id})
    }).catch(err => {
        // Set error status
        res.status(err.response.status)
        // Return json with score of 0 and error_message from API 
        return res.json({"score":0, "error_message":err.response.message})
    })
})

app.listen(process.env.PORT, process.env.HOST)