Introduction

In this section, we will take a look at the request and response parameters that are passed to the integration functions.

These parameters are passed as request data to the API integrations and are passed as function parameters to the main function in custom code integration.

Request Parameters

{
 "step": "system name of the step",
 "event": "API_INTEGRATION",
 "user": {
 "user_id": "User ID",
 "user_name": "haptik username",
 "full_name": "",
 "device_platform": 5,
 "language_code": "User's current language",
 "auth_id": "Authentication ID, If AuthInfo Is present else empty string",
 "auth_code": "Authentication Code, If AuthInfo Is present else empty string"
 },
 "conversation_no": 1,
 "conversation_details": {
 "insurance_no": "CDQP12324",
 "payment_mode": "COD"
 },
 "user_details": {
 "phone_number": 8826755986,
 "date_of_birth": "21/07/1995"
 },
 "entities": {
 "product_id": [
 {
 "detection": "message",
 "original_text": "71",
 "entity_value": "71"
 }
 ],
 "email": [
 {
 "detection": "user_profile",
 "original_text": "test@test.com",
 "entity_value": "test@test.com"
 }
 ],
 "product_name": [
 {
 "detection": "default",
 "original_text": "headphones",
 "entity_value": "headphones"
 }
 ]
 },
 "env_variables": {
 "CREATE_LEAD_API": "https://abc.com/create-lead",
 "CRM_INTEGRATION_API": "https://abc.com/crm-integration-api"
 }
}

1. Step - Unique system name of the calling step

2. entities - The entities dictionary will have a key for each entity that is detected e.g. movie_name, venue, phone_number, etc. The value for each entity is a list of dictionaries as shown below.

3. event - event type e.g. API_INTEGRATION

4. user - Dictionary containing user data

User data will be available across bots and businesses as long as the underlying user is the same in the database. The dictionary contains the following parameters:

user_name: user_name of the user in Haptik's system

full_name: full_name of the user

device_platform: device platform of the user. Please find the mappings below:

language_code: Current Language of the User

auth_id: Authentication ID, unique identifier of the user if passed via SDK else empty

auth_code: Authentication Code, if AuthInfo is a present else empty string

5. conversation_no - Identifier for the current conversation of the user with this Business

6. conversation_details - Conversation details store the current context of the conversation. Things like insurance number or product id which are the current scope of the conversation will go under conversation details.

This data will be stored in Redis with an expiry time of 3 hours.

7. user_details - user_details stores user's data like address, PAN number, Aadhar number which are independent of the current context of the bot conversation.

Data inside user_details will be available across bots and businesses as long as the underlying user is the same in the database.

8. env_variables - env_variables key returns environment variable values of the current environment. ENV variables can be added/edited by a developer from code executor UI.

entity output format

[
 {
 "entity_value": entity_value,
 "detection": detection_method,
 "original_text": original_text
 }
]

Consider the following example for a detailed explanation:

"I want to order from McD"

• entity_value: This will store the value of the entity (i.e entity value) that is detected. For example, McDonald's.
• detection: This will store how the entity is detected i.e. whether from the message, structured value, or fallback value.
• original_text: This will store the actual value that is detected. For example, mcd.

Response Parameters

A 200 OK HTTP Response must be sent back to the Haptik Servers, Failing which a bot break response will be sent to the user. API response must be sent in 30 seconds or less, failing which a bot break response will be sent to the user. The following additional fields can be specified by the API to control the behavior of the bot and send messages to the user.

{
 "response": [
 "message1",
 "message2",
 ....
 ],
 "status": True/False,
 "conversation_details": {}, // Optional
 "user_details": {} // Optional
}

status - Depending on whether the step is an end step or not, the True/False flag can affect the status of the chat.

response -Response will be an array of string(s) or HSL(haptik specific language).

for example:

1. Response with a single line

{
 "status": True,
 "response": ["phone number seems invalid, please try again"]
}

2. Response with multi-line

{
 "status": True,
 "response": ["phone number seems invalid", "please try again"]
}

3. Response for Multi-Lingual Bot

language_code = request_body['user']['language_code'] #assuming request_body contains post-data
if language_code == 'en':
 message = ["phone number seems invalid, please try again"]
elif language_code == 'hi':
 message = ["फ़ोन नंबर अमान्य लगता है, कृपया पुनः प्रयास करें"]
else:
 message = <Any Message as per use case>
{
 "status": True,
 "response": message # One we created above from conditional logic^^
}

4. Response with advanced UI elements for more detail read here

 {
 "status": true,
 "response": [
 '{
 "text": "COMPLETE BLOOD COUNT; CBC",
 "type": "BUTTON",
 "data": {
 "items": [
 {
 "actionable_text": "View Price",
 "location_required": false,
 "is_default": 0,
 "uri": "LAUNCH_CHANNEL",
 "type": "TEXT_ONLY",
 "payload": {
 "gogo_message": "",
 "message": "I want to check the price of this test"
 }
 },
 {
 "actionable_text": "View Details",
 "location_required": false,
 "is_default": 0,
 "uri": "LINK",
 "type": "APP_ACTION",
 "payload": {
 "url": "XYZ.COM",
 "gogo_message": ""
 }
 }
 ]
 },
 "isNew": false
 }'
 ]
 }

5. Response When conversation and User details need to be updated

{
 "status": True,
 "response": ["phone number seems invalid", "please try again"],
 "conversation_details": {
 "insurance_no": "CDQP12324",
 "payment_mode": "COD"
 },
 "user_details": {
 "phone_number": 8826755986,
 "date_of_birth": "21/07/1995"
 },
}

As per our pipeline, if there is no response at specific stages, then it will be treated as a Botbreak scenario. So if your Bot Response  section on Mogambo doesn't have any response or the integration function doesn't return any response, then a Botbreak message will be sent or the chat will be moved to Pending state depending on whether Human assistance is disabled or enabled respectively.