Chatbot API

API Declaration

The "token" param must be contained in the header of the https request when calling the API.

Token is the only global API call credential for the Sobot API open platform. It is used when developers call the business APIs and thus should be properly kept. At least 32 chars should be reserved to store token. The validity period of token is currently 24 hours. It needs to be refreshed regularly or reacquired according to the token failure prompt returned by the API. When requesting the token API, regardless of the existence of token, a new token will be returned and its expiry time will be reset (currently 24 hours).

Token usage description:

1. Developers need to obtain and manage the token uniformly. When calling the Sobot open APIs of various business, they should use the same token, instead of refreshing and obtaining new tokens for each business. Otherwise, it will easily lead to token invalidation and affect the normal API call.
2. The current validity period of the token is transmitted by the returned expire_in, which is currently a value within 86,400 s. Developers need to refresh the new token in advance based on this valid time.
3. Developers should reacquire the token according to the token invalidation prompt returned by the API.

API Call

● Get the Access Token Code

API description:

Get the open API token, which is only applicable to all APIs of Sobot Open Platform v5.0. Contact the Sobot after-sales service personnel to get appid and app_key in the API.

Request method:

GET

Request URL:

 https://sg.sobot.io/api/get_token

Request param:

Param	Type	Required	Description
appid	String	Yes	API credential ID
create_time	String	Yes	Timestamp
sign	String	Yes	Signature

Return param:

Param	Type	Required	Description
ret_code	String	Yes	Return code
ret_msg	String	Yes	Return message
item	Object	No	Return object

item object:

Param	Type	Required	Description
token	String	Yes	token code
expires_in	String	Yes	Credential valid time

Timestamp conversion tool:

https://www.unixtimestamp.com/

sign signature generation example:

E.g.: appid = "1"; create_time="1569397773"; app_key="2"

sign = Md5("115693977732") is 258eec3118705112b2c53dc8043d4d34.

Request example:

curl https://sg.sobot.io/api/get_token?appid=1&create_time=1569397773&sign=258eec3118705112b2c53dc8043d4d34

Return example:

{
    "item": {
        "token": "4ac37cb2e9c740dba4b75a34d5358802",
        "expires_in": "86400"
    },
    "ret_code": "000000",
    "ret_msg": "success"
}

● Get FAQ

API description:

API type: Active call API

API function: Support calling the FAQ list and guidance text of the designated bot configured in the Sobot backend

Request method:

POST

Request URL:

 https://sg.sobot.io/api/robot/5/get_robot_guide

Request param:

Param	Type	Required	Description
robot_flag	Integer	Yes	Bot no.
faqid	Number	No	FAQ group ID

Return param:

Param	Type	Required	Description
ret_code	String	Yes	Return code
ret_msg	String	Yes	Return message
item	Object	Yes	Return object

item object:

Param	Type	Required	Description
robot_flag	Integer	Yes	Bot no.
question_id	String	Yes	Question ID
link_question_num	Integer	Yes	No. of guidance texts
link_question_list	Object	Yes	Guidance text object
companyid	String	Yes	Company ID
guide_strip	String	Yes	Guidance text

link_question_list object:

Param	Type	Required	Description
match_flag	Integer	Yes	Match mode: 0-Intelligent match, 1-Exact match, 2-Containing match, 3-Greeting match
docid	String	Yes	Entry ID
guide_question_disname	String	Yes	Display name
guide_question	String	Yes	Standardized question

curl https://sg.sobot.io/api/robot/5/get_robot_guide 
-X POST 
-H 'token: c87c0dbac8c24261b9a4335fa5a51448 ' 
-H 'content-type: application/json' 
-d '
{
   "robot_flag": "1"
}'

Return example:

{
   "items": [],
   "item": {
       "robot_flag": 1,
       "question_id": "078726f1435b4218b9733afe2433b9fe",
       "link_question_num": 4,
       "link_question_list": [
           {
               "sort_no": 1,
               "match_flag": 0,
               "docid": "1b06cc8839574dc487bf658f0033bfb1",
               "guide_question_disname": "Can liquidated damages/late fees be invoiced?" ,
               "guide_question": "Can liquidated damages/late fees be invoiced?"
           },
           {
               "sort_no": 4,
               "match_flag": 0,
               "docid": "9b66fd499ff946df8213868bece0b0e3",
               "guide_question_disname": "Is there a house in Madrid that charges by the day",
               "guide_question": "Is there a house in Madrid that charges by the day"
           }
       ],
       "companyid": "0a53403cb9b34d528bdc11df69c283ff",
       "guide_strip": "<p test guide language!! </p"
   },
   "ret_code": "000000",
   "ret_msg": "success！"
}

● User Inquires Bot

API description:

API type: Active call API

API function: Support inquiring bot and getting answers as a user by calling this API

Request method:

POST

Request URL:

 https://sg.sobot.io/api/chat/5/user/robot_chat

Request param:

Param	Type	Required	Description	Remark
partnerid	String	Yes	The enterprise's user ID, which can be passed by the enterprise itself
question	String	Yes	User question	Refer to the table below for example details
user_nick	String	No	User's nickname
source	String	No	User channel	0: PC, 1: WeChat, 2: app, 3: Weibo, 4: Mobile site, 9: WeCom, 10: Mini program
robot_flag	String	No	Bot no.
question_flag	String	No	Problem Type	Question type: click -1, enter -0, click -2 in multi-round chat
request_text	String	No	Question content	questionFlag=0, pass the original question; questionFlag=1, pass docId; questionFlag=2, refer to the table below for example details
msg_type	Integer	No	Message type	0: Text, 1: Image, 3: Video, 4: File, default 0. Emoji is a file
lan_flag	Integer	No	Language tag	If you do not pass, default language in the channel or the language in the reception scheme in the user source channel is used. 0: Chinese (simplified), 1: English, 2: Chinese (traditional), 3: Arabic, 4: French, 5: Portuguese, 6: Korean, 7: Spanish, 8: Italian, 9: Japanese, 10: German, 11: Malaysian, 12: Indonesian, 13: Russian, 14: Thai, 15: Vietnamese, 16: Turkish
channel_flag	String	No	Sub-channel id	Pass according to channelid in Docking Channel Settings
reception_version	Integer	No	Reception version	0: v1 old version, 1: v6 new version, default 0. If the incoming version is V6 (1), but the actual highest configuration version of the company is V1 (0), it will not take effect and the version will be set according to V1 only.

question param details:

One-round: Pass user question

Multi-round: Determine the passing content according to the multiDiaRespInfo field in the last-round return value.

Key fields in multiDiaRespInfo : interfaceList and inputContentList, which will alternatively exist in the same-round return value

1) If the last round returns interfaceList, only json of template and interfaceRetList will be retained, where the interfaceRetList set only retains the selected set elements, for example:

		{
					"template":0,
					"question":"template one",
					"level":0,
					"conversationId":"5fcb4cb5-2078-41c7-bb9d-8fbf57464c94",
					"docId":" 1b8b2dcc4a8243649fa49744b9cf362b",
					"groupId":" 9a38730078354d4a832a6c621483ad9d",
					"remindQuestion":"Please select a movie:",
					"endFlag":false,
					"levelName":"movie",
					"retCode":"000000",
					"clickFlag":1,
					"interfaceRetList":[
						{
							"summary":"Good movie, don't miss it",
							"thumbnail":"",
							"anchor":"http://www.baidu.com",
							"movieId":"1",
							"tag":"Released in 2020",
							"label":"Released in 2020",
							"title":"Released in 2020"
						},
						{
							"summary":"Excellent film",
							"thumbnail":"https://ilw.aliimg.com/media/lADODuM9KM0E2s0E1w_1239_12jpg",
							"anchor":"http://www.sina.com",
							"movieId":"3",
							"tag":"Not shown",
							"label":"00",
							"title":"Rise of the Planet of the Apes"
						}
					],
					"outPutParamList":"title#movieId"
				}
			//If the customer selects the option with title "Transformers III", the passed data is: 
                {
					"template":0,					
					"interfaceRetList":[
						{
							"summary":"Good movie, don't miss it",
							"thumbnail":"",
							"anchor":"http://www.baidu.com",
							"movieId":"1",
							"tag":"Released in 2020",
							"label":"00",
							"title":"Released in 2020"
						}
					]
				}

2) If inputContentList is returned in the last round, the selected value will be passed in directly. For example:

{
	"template":0,
	"question":"I want to buy a mobile phone",
	"level":0,
	"conversationId":" a4bb45ed-594e-4953-b74e-e2f91337f",
	"docId":" 022e96da2f8346b7bfb0efb400a9c558",
	"groupId":" 9a38730078354d4a832a6c621483ad9d",
	"remindQuestion":"Please select brand",
	"endFlag":false,
	"levelName":"brand",
	"retCode":"000000",
	"inputContentList":"Huawei, Apple, Xiaomi",
	"outPutParamList":"brand"
}

Select Huawei in the inputContentList, and the passed data is Huawei;

request_ Text param details:

One-round: optional field; Multi-round: required. Determine the passing content according to the multiDiaRespInfo field in the last-round return value. Key fields in multiDiaRespInfo : interfaceList and inputContent, which will alternatively exist in the same-round return value.

1) If the last round returns interfaceList, json composed of the corresponding values of level, conversationId and outPutParamList of the last-round chat will be returned. Return json composed of the corresponding values of level, conversationId and outPutParamList of the last-round chat, for example: {"outPutParamList in the last-round chat": "xxx", "level": 0, "conversationId": "xxx"}) For example:

{
	"template":0,
	"question":"template one",
	"level":0,
	"conversationId":" 5fcb4cb5-2078-41c7-bb9d-8fbf57464c94",
	"docId":" 1b8b2dcc4a8243649fa49744b9cf362b",
	"groupId":" 9a38730078354d4a832a6c621483ad9d",
	"remindQuestion":"Please select a movie:",
	"endFlag":false,
	"levelName":"movie",
	"retCode":"000000",
	"clickFlag":1,
	"interfaceRetList":[
		{
			"summary":"Good movie, don't miss it",
			"thumbnail":"",
			"anchor":"http://www.baidu.com",
			"movieId":"1",
			"tag":"Released in 2020",
			"label":"01 yuan",
			"title":"Transformers III"
		},
		{
			"summary":"Excellent film",
			"thumbnail":"https://ilw.lmg.com/media/12jpg",
			"anchor":"http://www.sina.com",
			"movieId":"3",
			"tag":"Not shown",
			"label":"00",
			"title":"Rise of the Planet of the Apes"
		}
	],
	"outPutParamList":"title#movieId"
}

If the customer selects the option with title "Transformers III", the passed data is:

{
	"level":0,
	"conversationId":"5fcb4cb5-2078-41c7-bb9d-8f464c94",				
	"movieId":"1",
	"title":"Transformers III"
}

2) If the last round returns inputContentList, json composed of the corresponding values of level, conversationId and outPutParamList of the last-round chat will be returned. For example:

{
	"template":0,
	"question":"I want to buy a mobile phone",
	"level":0,
	"conversationId":"a4bb45ed-594e-437f",
	"docId":"022e96da2f8346b7bfb0efb400a9c558",
	"groupId":"9a38730078354d4a832a6c621483ad9d",
	"remindQuestion":"Please select brand",
    "endFlag":false,
    "levelName":"brand",
    "retCode":"000000",
    "inputContentList":"Huawei, Apple, Xiaomi",
    "outPutParamList":"brand"
}

Select Huawei in the inputContentList, and the passed data is:

{
	"level":0,
	"conversationId":"a4bb45ed-594e-4953-b74e-e2f1337f",
	"Brand": "Huawei"
}

Return param:

Param	Type	Required	Description
ret_code	String	Yes	Return code
ret_msg	String	Yes	Return message
item	Object	No	Return object

item object:

Param	Type	Required	Description
answer	String		Answer
answers	List		Two or more messages. If this field exists, answer field will be null. 20220901 new param
suggestions	List		Recommended question list. For details, see the text below
question	String		Original question, entry name
docid	String		Entry ID
visitorid	String		User ID
cid	String		Chat ID
msgid	String		Message body ID. When answer field is not null, this field has a value
stripe	String		Question recommendation guidance text
robot_flag	String		Bot no.
answer_type	String		Bot answer type
gpt_answer_type	String	No	Sobot AI answer type, 1-direct answer
session_new	String		Whether it's a new chat
transfer_type	String		Trans-to-agent trigger type: 0: Not trigger, 1: Repeat question, 2: Negative emotion, 3: Hit keyword, 4- Hitting Multi-Round Rules, 5-Bot Auto, 11-Multi-Rounds Node Trans-to-Agent
transfer_flag	String	No	Multi-Rounds Node Trans-to-Agent: 0-By Customer Assignment Setting, 1- Designated Agent, 2-Designated Skill Group
transfer_targetid	String	No	Multi-Rounds Node Trans-to-Agent target id: Agent or Skill Group id
multi_response_info	Object		Multi-round chat return data
answerid	String		Answer ID. When answer field is not null, this field has a value. 20220901 new param
ruleid	String		Rule ID. 20220901 new param
kbid	String		Knowledge base ID. 20220901 new param
kb_name	String		Knowledge base name. 20220901 new param
special_msg_flag	Integer		Robot special messages (pictures, videos, files, emoji) Matching identifier 0 No matching identifier 1 Matching identifier. 20250415 new param

answers object:

Param	Type	Required	Description
answerid	String		Answer ID
msgid	String		Message ID
answer	String		Answer

suggestions object:

Param	Type	Required	Description
question	String		Recommended question name
answer	String		Recommended question answer
docid	String		Recommended question entry ID

multi_response_info object:

Param	Type	Required	Description
remind_question	String		Bot prompt question
answer_strip	String		Answer guidance text
interface_ret_list	List		API return list
input_content_list	String		Custom list content
output_param_list	String		Pass in param in the next-round chat
level	Integer		Round level
level_name	String		Round level name
question	String		Original question
answer	String		Answer
ret_code	String		Call API return code
ret_error_msg	String		Call API return description
docid	String		Recommended question entry ID
conversationid	String		Multi-round chat ID
template	Integer		Template ID
end_flag	Boolean		Multi-round chat end tag

Request example:

curl https://sg.sobot.io/api/chat/5/user/robot_chat 
-X POST 
-H 'content-type: application/json' 
-H 'token: c87c0dbac8c24261b9a4335fa5a51448 ' 
-d '
{
	"partnerid" : "xx",
	"question" : "xx"
}'

Return example:

{
    "item":{
        "answer":"xx",
        "answers":[
            {
                "answer":"xx",
                "answerid":"xx",
                "msgid":"xxx"
            }
        ],
        "suggestions":[
            {
            	"question":"xx",
            	"answer":"xx",
            	"docid":"xx"
            }
        ],
        "question":"xx",
        "docid":"xx",
        "userid":"xx",
        "cid":"xx",
        "msgid":"xx",
        "stripe":"xx",
        "robot_flag":"1",
        "answer_type":"1",
        "session_new":"true",
        "transfer_type":"1",
        "answerid":"xxx",
        "ruleid":"xxx",
        "kbid":"xxx",
        "kb_name":"xxx",
        "special_msg_flag":1
    },
    "ret_code":"000000",
    "ret_msg":"success"
}

● User input to call word association

API Description:

API type: Active call API

API function: You can obtain the word association results for input questions in the corresponding knowledge base by calling the API

Request method:

POST

Request URL:

 https://sg.sobot.io/api/chat/5/user/query_suggest

Request param:

Param	Type	Required	Description	Note
partnerid	String	Yes	The enterprise's user ID, which can be passed by the enterprise itself
question	String	Yes	User question	Users search the word association problem
robot_flag	String	No	Bot no.	Default:1
num	Integer	No	Number of associated word entries

Return param:

Param	Type	Required	Description
ret_code	String	Yes	Return code
ret_msg	String	Yes	Return message
item	Object	No	Return object

item object:

Param	Type	Required	Description
originQuestion	String		Query original question
respInfoList	List		Word association result array. For details, see the text below

respInfoList object:

Param	Type	Required	Description
docId	String		Word association problem entry ID
questionId	String		Word association problem ID
question	String		Name of the word association problem
highlight	String		Display and highlight word association problems

Request example:

curl https://sg.sobot.io/api/chat/5/user/query_suggest \
-X POST \
-H 'token:056b5b979ff54753869e3deef6a657d6' \
-F 'partnerid=xx' \
-F 'question=what' \
-F 'num=5' \
-F 'robot_flag=1'

Return example:

{
    "respInfoList": [
        {
            "questionId": "2939578d354d4850a3d7b789dcb54caa",
            "question": "what??",
            "docId": "07a917c9b6734f65a1145a80a84e5e3f",
            "highlight": "<font color='red'>what</font>??"
        }
    ],
    "originQuestion": "what"
}

● Bot Answer Evaluation

API description:

API type: Active call API

API function: Support evaluating bot answer (instead of chat) by proactively calling this API

Request method:

POST

Request URL:

 https://sg.sobot.io/api/chat/5/user/robot_feedback

Request param:

Param	Type	Required	Description
visitorid	String	Yes	Visitor ID
cid	String	Yes	Chat ID
docid	String	Yes	Entry ID
doc_name	String	Yes	Entry name
robot_flag	String	Yes	Bot ID
status	String	Yes	Evaluation status
msgid	String	Yes	Message ID. If the answers field of bot inquiry API has a value, pass msgid in answers
partnerid	String	No	The enterprise's user ID, which can be passed by the enterprise itself
from	String	No	Customer Source
answerid	String	No	It is optional for one-round question
ruleid	String	No	It is required to pass for rule answer
answer	String	No	It is required to pass for multi-round question

Note: In case of no visitorid, partnerid or from can be passed in

Return param:

Param	Type	Required	Description
ret_code	String		Return code
ret_msg	String		Return message
item	Object		Return data

item object:

Param	Type	Required	Name
ustatus	String		User status -2: Queuing, -1: Bot, 0: Offline, 1-: Online

Request example:

curl https://sg.sobot.io/api/chat/5/user/robot_feedback 
-X POST 
-H 'token: c87c0dbac8c24261b9a4335fa5a51448 ' 
-H 'content-type: application/json' 
-d '
{
    "cid": "a09b71ae2abd4604aba1c9961bc31095",
    "msgid": "2cfd756f0077406ea22d1efe75555c55",
    "docid": "317f5b28887544d0be69f7e1520b269d",
    "doc_name": "Video and text",
    "robot_flag": "1",
    "status": "1",
    "visitorid": "ab48f1e755ac766d8732501a3ef1a116"
}'

Return example:

{
    "item": {
        "ustatus": "-1"
    },
    "ret_code": "000000",
    "ret_msg": "success"
}

One-round Chat API Call

● One-round Chat Application Scenarios

In addition to answering questions based on the knowledge base, Sobot chatbot can also call information based on the third-party API.

For example, express companies hope that users can query express delivery information by themselves when communicating with chatbot, so they can set up a question for chatbot to call the express query API in the knowledge base for this scenario.

When this question is triggered during user interaction, the bot can pass the express waybill number that the user wants to query to the query API, and then send the information returned by the query API to the user to realize user self-service query.

For example, if the user enters the order number: 12345678 for query, the bot will call the order query API and pass the user information and the order number 12345678 to the query API. If the query API returns the query results normally, the bot will display the query results to the user.

● How to Set

Setting item description:

Users of Enterprise and higher versions can view the optional API call types when they click Add Question in the knowledge base. After selection, it will display relevant setting items.

The meaning of each setting item is as follows:

Standardized question: the keyword that triggers query API in words entered by users. The keyword must be at the beginning of a single entry.

For example, if the standardized question is set to order query, "order query: 12345" can correctly trigger API call, while "can you make order query" won't trigger API call. The matching (keyword matching) priority of the API call question will be higher than that of other questions. However, in order to avoid confusion in knowledge base maintenance, please try to avoid consistency or inclusion with the standardized question of other questions.

API URL: the URL of calling API

http://www.test.com/Order

Parameters: Parameters that need to be extracted from user input and passed by the bot when calling the API.

Parameter name: The parameter name used when passing the parameter. For example, OrderID: the bot will assign a value to the OrderID and pass it when calling the API.

Length limit: Limit the length of this parameter. If the parameter entered by the user exceeds this length, the bot will show the call description to the user.

Parameter description: The note description of this parameter. Chatbot will not use this information.

Separator: The symbol used for separating from the previous parameter or standardized question keyword. It can be set to space, colon, comma, underscore, bracket, etc.

Token: The token passed when calling the API, which can be generated randomly or customized. It can be used for identity authentication of the Sobot chatbot when calling the API.

Call description: When a user triggers API call, but does not enter the required parameters correctly, the bot will display the content set here to the user.

Timeout description: If error information or timeout is returned when calling the API, the bot will display the content set here to the user.

Select category: The category of the question in the knowledge base.

Valid time: The valid time of the question.

Enabling status: The enabling status of the question.

Set example:

Standardized question: Weather query

API URL:

http://www.test.com/weather/query?

Add parameters:

Param name	Length Limit	Param Description	Separator
key	40	Call API	#
cityname	10	Query city name	#

Token: de8devfjtf8cj7eogi9el (randomly generated)
Call description: If you want to query the weather forecast, please ask questions in the following format: weather query #ddXXXXXXXXXXXX12dd# Shanghai
Timeout description: Network connection timeout, please try again later.

Call trigger description:

For the above example, the description of the user entering different content.

Query the weather forecast (not trigger API call)
How to query the weather forecast? (not trigger API call)
Weather query (trigger API call, but due to parameter input error, the bot returns the call description to the user)
Weather query: Madrid (trigger API call, but due to parameter input error, the bot returns the call description to the user)
Weather query #123456# Shanghai (trigger API call, and the bot will call the third-party API and pass 123456 as the key parameter value and Shanghai as the cityname parameter value)

Parameter passing:

When calling API, the bot will pass parameters in POST mode.

Fixed parameters:

Fixed parameters refer to the parameters that the bot will pass when calling the API regardless of setting. Including:
partnerid: User docking ID. For relevant information, refer to Sobot System Access Guide
token: Token field filled in during setting

Custom parameters:

Custom parameters refer to the parameters added during setting. The bot will extract parameters according to the user input sequence and separator. If the parameters are extracted correctly, they will be passed to the API.

● API Return Format

API return result shall be in JSON format, including the parameters below:

Name	Type	Description
ret_code	int	Query status return code, 0: return for correct query, 1: return for incorrect query
ret_message	string	The query return results, that is, the information displayed to the user, support basic html tags, including images, text fonts and typesetting codes.

Example of data returned by the API:

{
    "ret_code": 0,
    "ret_message": "Today is Wednesday, the fourth day of the second month of the lunar calendar, the temperature is 5℃, the humidity is 12, the wind direction is north, the wind force is 3."   
}

● Other Notes

API call timeout duration:

When API call does not return a valid result within 2000 milliseconds, the bot will judge it as API call timeout and show the call timeout description to the user.

Encoding format:

When calling API, the bot will encode and pass parameters in UTF-8 format. The data returned by API shall also be encoded in UTF-8 format.

Returned answer length:

It is suggested that the returned answer should be less than 2000 chars. Excessively long answers will affect the reading efficiency of users and will not be conducive to display.

Multi-round Chat API Call

● Multi-round Application Scenarios

Multi-round chat API has the following two application scenarios: get variables only and get message contents.

1.Get variables only

The application scenario is to call the API once to get the variables after hitting multi-round questions to provide the judgment basis for subsequent nodes. For example, when answering questions related to 「Social insurance」, it needs to get the social insurance location of the employee from the API. The content obtained by the API is not used directly for chat interaction.

Set an entry to correspond to the screenshot below.

2.Get message contents

The application scenario is to get the contents sent by bot from the API. For example, users should select the order list when questions related to「Check logistics info」 are made; the collected info will be pushed to the invoice API, and customers will be informed whether the operation succeeded when questions related to「Invoice」 are made.

The following figure shows a screenshot of the system configuration (it describes the API configuration of the answer node, which differs slightly from that of the condition node).

● Template pattern and param overview

1.Template 1

2.Template 2

3.Template 3

4.Template 4

5.Custom Template

Correspond the message the bot is expected to send to the tempStr param. See 「Request Param」section for details.

6.Not Select Template

Correspond the message the bot is expected to send to the title param. See 「Request Param」section for details.

● API Configuration

When calling the API in multi-round chats, you should first configure the API according to the screenshot path.

You can customize the Header param, request param, and output param. Custom request param can be associated with variables collected in the multi-round chats. Output param will assist the multi-round bot in making subsequent conditional judgments.

● Request Param

As in the screenshot above, partnerId and multiParams are fixed input params, and you can customize params (info collected in multi-round chats can be associated to the custom param).

Field name	Field description	Type
partnerId	Customer docking ID you passed into Sobot when the chat started. Blank when no params passed in	Fixed param
multiParams	The multiParams you passed in when the chat started, with a json key-value pair format, e.g.: {"city":"Madrid","category":"Shirt"}. Blank when no params passed in	Fixed param
source	Chat channel. 0: Desktop site (PC), 2: APP, 4: Mobile site (H5)	Fixed param
robotNo	ID of the bot calling the API. See robotId in the bot info for details	Fixed param
docId	ID of the question calling this API	Fixed param
Custom param	Request param you customized. Values are derived from the specific configuration of multi-round questions	Custom param

#Request example

curl https://xxxx.com/api/xxxx
-X POST
-H "Content-Type:application/x-www-form-urlencoded" 
-H "Custom Header1:header value 1" //Backend custom header param 1
-H "Custom Header2:header value 2" //Backend custom header param 2
-D "partnerId=xxx&multiParams={\"xx\":\"xx\"}&token=xxxx&source=0&robotNo=1&docId=xxxx&custom param name 1=value 1&custom param name 2=value 2//Request param includes fixed param and backend custom param

● Return param

There are various cases of multi-round application scenarios. Please use the list form uniformly and return the param according to the following specifications. The case that does not involve a list is also included (place the custom output param in the list as well). Return param should be pushed within 5s; otherwise, the bot will take it as cases for answers not found.

1.Please note that the title param must be passed in. See the examples below for details

1.1 Return example - Normal condition

"code":"000000" represents the normal condition. For example, there are orders under the user's name when checking the logistics info. The specifications are as follows:

{
     "code": "000000", //'000000' represents success 
     "robotMsg": "Bot message", //If it is passed in, it will replace the「Bot Question Guidance」 and 「Answer Guidance Text」 configured on the interface. "\n" can be added in the text to achieve the line feed effect (only available for new version PC/H5 ("V2" when accessing url), and SDK 2.8.2 and above versions). Please note that when the template type is「Not Select Template」, the text content sent by the bot should be transmitted through the "title" param below 
     "list": [
         {
             "id": "Param ID",
             "title": "Title", //Must return the param. When the template type is 「Not Select Template」, the text content sent by the bot should be transmitted through this param
             "summary": "Summary",
             "tag": "Tag (multiple items can be displayed)",
             "label": "Price||Score||No. of people want to watch||No. of people and all other display items not containing multiple tags",
             "thumbnail": "Preview image URL",
             "anchor": "Click to jump to the URL",
         },
         {
             "id": "Param ID",
             "title": "Title",
             "summary": "Summary",
             "tag": "Tag (multiple items can be displayed)",
             "label": "Price||Score||No. of people want to watch||No. of people and all other display items not containing multiple tags",
             "thumbnail": "Preview image URL",
             "anchor": "Click to jump to the URL"
         }
     ]}

1.2 Return example - Abnormal condition

"code":"000001" represents the abnormal condition. For example, there is no order under the user's name when checking the logistics info.

In this case, the bot will send the content returned by errorMsg and terminate the multi-round chat.

{
    "code": "000001", //'000001' represents that the API returns the custom abnormal prompt info
    "errorMsg": "Abnormal info description" //Bot displays the content
}

● Case

Third-party APIs can be associated forward and backward through custom params. For example, in the multi-round chat of 「I want to watch a movie」, the first node is 「City node: please click your city」, and the second node is 「Cinema node: please select a cinema」. At this time, the option list of cinemas depends on the city selected in the first round, and the params of the first round API need to be passed.

So, the first node for getting the 「Get City API」 returns the following API results:

{
     "code": "000000",
     "list": [
         {
             "title": "Madrid",
             "cityId": "1" //City ID 
         },
         {
             "title": "Shanghai",
             "cityId": "2" //City ID 
         }
     ]
}

When configuring 「Get Cinema API」, the request param cityId should be added.

When configuring the node for selecting a cinema, the content obtained in「City」 variable should be associated to the custom request param cityId of 「Get Cinema API」.

Add API node branches. When the「City」 variable is selected as 「 Madrid」, 「Get Cinema API」 will request the available cinemas with cityId = 1.

Error code

Error code	Error description
000000	Operation done (Any code other than this code is an error code)
220001	The length of [x] exceeds the maximum limit of [y] characters.
220006	The value of [x] cannot be converted to the desired type.