Skip to main content

Getting Started

This document illustrates the development of APIs for Helpshift Custom Bots. Following steps describe how to create and configure APIs for managing custom bots.

Configuring APIs

  1. Configure API Requests that can retrieve and update data on the external system. Navigate to the External API Requests section in the Helpshift Admin dashboard.
    • Provide the setup details and input parameters.
    • Test the API with dummy values for the input parameters.
    • View response and select the keys that you want to use in the Bot Builder. Valid JSON formats support the response.
  2. Configure the APIs in the Bot Builder to build the interactions that Bot will have with the end-user. Make an API Request enables you to consume the configured APIs.
    • In the Make an API Request step, select an API that you want to use.
    • Test the API to check the data transfer and whether the endpoint is working.
    • During the Bot conversations, enter the values that you want to pass using the APIs (CIFs, user details, information from earlier bot steps, etc.)
  3. Use the API response via the Success branch of the Make an API Request step.
    • Use the response to build Bot messages using placeholders wherein you can plug the API response.
    • Branch a conversation by setting up rules, if the API response is of type Date, Number or Boolean.
    • Generate a list of options (order list, for example) for the end-user to select from.

Types of HTTP Methods Supported

RetriveGETretrieve multiple issues
Create/UpdatePOST/PUTretrieve single issue

Setup APIs

Title-Mandatory
URL-Mandatory
TypeGET, POST, PUTMandatory
AuthenticationBasic HTTP, CustomMandatory
Type of encoding for POST / PUTapplication/x-www-form-urlencoded, application/jsonMandatory
Parameters for the API-Optional, advised to send at least one parameter
Format for GEThttps://www.xyz.com/?param1=valm2=valueKey and value both will be sent in the request URL.
Request sizeUpto 20 KBStrictly followed; if exceeded, error will be displayed.
Response sizeUpto 100 KBStrictly followed; if exceeded, error will be displayed.

API Request and Response

POST / PUTFor encoding ‘application/json’, values of keys will be sent as strings irrespective of actual data type.
AuthenticationIf the customer endpoint has no authentication or the request contains incorrect credentials,
the expected response is 401 (Unauthorized) or 403(Forbidden).
Timeout5 seconds
Status Codes
  • Success - 2XX
  • Failure - 3XX, 4XX, 5XX
  • Redirects are not supported
Response keysAdmin optionally has the flexibility of using specific keys (not all) from the API response.
Response formatOnly valid JSON
Date typeWe will send date in the format “yyyy-mm-dd” for Requests.
For Responses, if a string follows the pattern “yyyy-mm-dd”,
we will consider it to be of type ‘date’.

API Requests during Bot executions

Things to avoid
  • Multiple API calls in succession.
  • Requests to public APIs (like Google Maps) using Helpshift Bots is not recommended;
    in such cases, it is advisable to call your endpoint and have your backend service make those public calls.
ParametersFor parameters that have no value in the system, for example CIF,
the key will be passed with values in the following format.

GET (Param1 has no value)
  • url/param1=&param2=some_value
POST/PUT (Param 1 has no value)
  • application/www-form-urlencoded
    • param1=&param2=some_value
  • application/json
    • {param1=NULL;}
HeaderX-hs-request-id (This should be used to de-duplicate requests)
Response used for
  • Constructing Bot messages with data received in API response
  • Generating list of options from which a user can make a selection (SDK - v7.5.0 will introduce a new UI element - List Picker to show up to 500 options)

Sample Responses

Valid
Valid - Example 1 {
  "balance": 500
}
Valid - Example 2 {
  "name": "John",
  "age": 25,
  "zip": 60616
}
Valid - Example 3 {
  "orders":[
    { "order_id":212, "order_title":"Baa Baa Black Sheep" },
    { "order_id":333, "order_title":"Jingle Bells" },
    { "order_id":444, "order_title":"There's a hole in the bucket" }
  ]
}
Valid - Example 4{
  "abc": {
    "a": {
      "b": [ 1, 2, 3 ],
      "c": true
    }
  }
}
Valid - Example 5{
  "issue_types": ["loyalty points", "loyalty privileges", "redeem points"]
}
Invalid
Invalid - Example 1
Response contains maps with separate structures.
{
  "xyz": [
    {
      "a": [ 1, 2, 3 ]
    }
  ],
  "pqr": [
    [ 1, 2, 3 ],
    [ 4, 5, 6 ]
  ]
}
Invalid - Example 2
Array contains values of different types.
{
  "a": [ 1, "hello", true ]
}
Invalid - Example 3
Array contains values of different types.
With Helpshift Bots, if strings have the format of “YYYY-MM-DD” it is considered type ‘date’.
{
  "a": [ "2019-01-17", "hello"]
}
Invalid keys containing nested array and maps values{
  "xyz": [
    {      
"a": [1, 2, 3], // invalid key as nested array is not allowed
      "b": "1",
      "c" :{"d": 1} // invalid as nested maps inside array is not allowed
    }],
    "pqr": [
      [1, 2, 3],
      [4, 5, 6]
    ], // invalid key again nested array is not allowed
    "abc": {
      "a": {
        "b": [1, 2, 3],
        "c": true
      }
    }
  }