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	retrieve multiple issues
Create/Update	POST/PUT	retrieve single issue

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¶m2=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       }     }   }