Methods

Available API features

Note: All examples shown are set in a Production environment.

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)

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.

addMultipleVariables(variableList)

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

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)

This method retrieves the Chatbot answer for a given query. The options parameter is optional, and only used to select one option among several.

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.

getVariables(configuration) This method returns every variable previously set in the conversation.

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.

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.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.

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.

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.

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.

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.

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.

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