Custom Bots API

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
Retrive GET
Create/Update POST/PUT

Setup APIs
Title - Mandatory
URL - Mandatory
Type GET, POST, PUT Mandatory
Authentication Basic HTTP, Custom Mandatory
Type of encoding for POST / PUT application/x-www-form-urlencoded, application/json Mandatory
Parameters for the API - Optional, advised to send at least one parameter
Format for GET https://www.xyz.com/?param1=val&param2=value Key and value both will be sent in the request URL.
Request size Upto 20 KB Strictly followed; if exceeded, error will be displayed.
Response size Upto 100 KB Strictly followed; if exceeded, error will be displayed.

API Request and Response
POST / PUT For encoding ‘application/json’, values of keys will be sent as strings irrespective of actual data type.
Authentication If the customer endpoint has no authentication or the request contains incorrect credentials,
the expected response is 401 (Unauthorized) or 403(Forbidden).
Timeout 5 seconds
Status Codes
  • Success - 2XX
  • Failure - 3XX, 4XX, 5XX
  • Redirects are not supported
Response keys Admin optionally has the flexibility of using specific keys (not all) from the API response.
Response format Only valid JSON
Date type We 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.
Parameters For 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;}
Header X-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
      }
    }
  }
Copyright © 2023 Helpshift Inc.
Call Us: (888) 983-2664