Available API features

If you are using the adapters, you can access the API client through the bot instance used as an entry parameter of the function:

function(bot) {
    var ChatbotAPI = bot.api //Apiclient methods can be accessed using the ChatbotAPI
}

apiClient(token: Object, configuration: Object, key: String)

This method creates an API client instance with the parameters provided. You need your access token to authorize the client to use the API.

token{
    accessToken: <your_access_token>
    expiration: <expiration>
}

The expiration parameter is optional. If no expiration is defined, the system runs a refreshtoken() at the start of the initialization.

The configuration parameter defines the usertype, environment and the bot configuration.

Example:

  configuration = {
    environment: "development",
    usertype:0,
    lang:'en',
    answers:{
      answerAttributes: ['ANSWER_TEXT'],
      sideBubbleAttributes: ['SIDEBUBBLE_TEXT'],
      maxRelatedContents: 3
    },
  };

API Client methods

Once you start the API Client, it exposes the following methods:

• addVariable(name, value)
• addMultipleVariables(variableList)
• conversation(query:String, option:String)
• destruct
• getAppData(AppDataInfo)
• getConversationHistory
• getVariables(configuration)
• getVariablesOptions(variableList)
• getSurvey(SurveyID)
• getToken
• languageDetector
• resetVariables(variableList)
• rateContent(trackingCode:String,value:String,comment:String)
• startConversation
• setAccessToken(accesToken: String, expiration: Number)
• track(eventName:String, data:Object)
• sessionUser(user_info)

addVariable(name, value)

This method sets a variable value on the current conversation. You can use it later, for example to avoid repeating questions to the user for which you already know the answer.

This method returns a Promise with the API response data.

addMultipleVariables(variableList)

This method sets multiple variables, name and value of every variable must be specified in the variableList parameter.

This method returns a Promise with the API response data.

The following example sets 2 variables, first_name and last_name:

var variableList =
[
    {
      name: "first_name",
      value: "John"
    },
    {
      name: 'last_name',
      value: 'Doe'
    }
];

bot.api.addMultipleVariables(variableList);

conversation(query:String, option:String, directCall:String)

This method retrieves the Chatbot answer for a given query.

It accepts the following parameters:

• query user question to be sent to the Chatbot.
• options is only used to select one option among several when the Chatbot shows multiple options.
• directCall lets you fetch a response via a Direct Call. If the direct call is set, it will fetch a response via Direct call, regardless of the other parameters.

This method returns a Promise with the API response data.

destruct()

This method deletes the apiClient interval to avoid leaving orphan processes when apiClient is no longer needed.

getAppData(AppDataInfo)

Returns application-related data defined in the Knowledge Base.

AppDataInfo Object

• dataID String: Extra info group name identifier from the Chatbot App Knowledge Base.
• name String (optional) : Extra info name element from the Chatbot App Knowledge Base.

• Return results Promise: The result will have the following format in a promise format:

  results: [
  name: "projectLanguages",
  group_name: "example",
  value: [
   {
     "languages": [
         "en",
         "es",
         "it"
     ]
   }
  ]
  ]

getConversationHistory()

This method uses the API to retrieve and return the conversation history.

This method returns a Promise with the API response data.

getVariables(configuration)

This method returns every variable previously set in the conversation.

This method returns a Promise with the API response data.

The configuration parameter is an Object with the following attribute:

• revealValues(boolean): If it is set to true, it returns the obfuscated variables. If false, it is hidden.

The following example display all the variables, even the obfuscated ones:

var variableConfiguration = {
    revealValues:true
}
bot.api.getVariables(variableConfiguration);

getVariablesOptions(variableList)

This method returns information about the given variables, current assigned value, scope and possible values if the type of the variable is List.

This method returns a Promise with the API response data.

VariableList parameter is a list of names of variables

• variableList(Array of Strings): names of the variables requested.

The following example will ask for the type of vehicle and colour:

var variableList = ['vehicle','colour']
bot.api.getVariablesOptions(variableList);

The response format is the same as documented in the Chatbot API variables/options endpoint response:

• variableName Object
• variableName.currentValue String : Current value of the variable or null.
• variableName. folderListHierarchy [Object] : Folder list hierarchy. Returned only in folder list variables.
• variableName. folderListHierarchy.id String : Folder id
• variableName. folderListHierarchy.name String : Folder name
• variableName. folderListHierarchy.children array : Children folders of the current folder. Properties: id, name and children
• variableName.scope String: Scope of the variable, which will have one of the following values: always | withinIntent | dataFieldOnly | validationOnly
• variableName.values Array of Objects : List of the possible values of the variable
• variableName.values.label Array of String : List of the possible labels of this variable option.
• variableName.values.option String :Value of the given option.

getSurvey(SurveyID)

The surveyID must match an existing Survey in the Chatbot instance. Contact Inbenta support to activate Surveys in your instance.

• number: The SurveyID must be the same as an existing survey ID.

It returns the URL of the given Survey. You must initiate a session before you can ask for the surveyID.

• Return url Promise: Returns a promise with String URL parameter.

getToken()

This method retrieves the current authorization token and token expiration being used by the API Client.

languageDetector

Endpoint useful only for multi-language instances

Returns the language of the user questions taking into account only the languages of the related instances. When the query is in another language, the endpoint returns the language of the current instance.

This method returns a Promise with the API response data.

bot.api.languageDetector(lastUserInput);

resetVariables(variableList)

This methods resets a list of variables to their default value, if no default value was assigned, it will be set to null.

This method returns a Promise with the API response data.

The following example resets 2 variables, first_name and last_name:

var deleteVariableList = [
  "first_name",
  "last_name"
]

bot.api.resetVariables(variableList);

rateContent(trackingCode:String,value:String,comment:String)

This method logs a rating using the trackingCode given in an Answer, with a value, and optionally a comment on this rating.

This method returns a Promise with the API response data.

startConversation()

This method starts a session and retrieves a token to maintain it. It uses the same bot configuration that created the API Client. For more information on available configurations, see the payload/conversation endpoint section.

This method returns a Promise with the API response data.

setAccessToken(accesToken: String, expiration: Number)

This method sets a new authClient expiration and accessToken. It updates the clientAxios accessToken. This is useful if the authorization is performed server-side and an unauthorized request has been made: you can set a new accessToken.

track(eventName:String, data:Object)

Remember to set up the session before calling this function.

This method returns a Promise with the API response data.

For more information about events and their specific data, see the tracking events section of the Developers Portal.

The following example is set to track a custom Event:

bot.api.track('CustomEvent',{value:"CustomValue"})

sessionUser(user_info)

This method saves the user information. It uses the information provided by the user_info variable.

This method returns a Promise with the API response data.

var user_info = {
  browserInfo: navigator.userAgent
}
bot.api.sessionUser(user_info);

It can include the special parameters inbenta_extra_field1, inbenta_extra_field2 and inbenta_extra_field3. Use these parameters to filter the results returned in the Reporting API's session_details aggregate by a specific value.

var user_info = {
  inbenta_extra_field1: 'Inbenta',
  inbenta_extra_field2: 'Barcelona',
  inbenta_extra_field3: 'Developer'
}
bot.api.sessionUser(user_info);