Chatbot Studio API Documentation

Introduction

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

Chatbot Studio

To start using LeadDesk Chatbot Open API, an organisation must generate a Developers API key. To do this, in Chatbot Studio:

1. Click your user name in the top right of Studio.
2. Click Settings.

In the Developer settings section, you can:

• Create an API key if you do not have one. Click the Create API key button.
• Click the Copy button to copy the URL of the environment’s Developers API.

After the token is created it will be displayed the Developer settings section. You will be able to reset it to generate a replacement. Any token created before Developer actions have been enabled by LeadDesk 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"
}'

Chatbot Studio

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

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)