Chatbot API
# 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:
- 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.
- 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.
- 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:
http://tool.chinaz.com/Tools/unixtime.aspx
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"
}
2
3
4
5
6
7
8
# ● 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"
}'
2
3
4
5
6
7
8
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!"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# ● 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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
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"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
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"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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
3
4
5
6
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"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
Select Huawei in the inputContentList, and the passed data is:
{
"level":0,
"conversationId":"a4bb45ed-594e-4953-b74e-e2f1337f",
"Brand": "Huawei"
}
2
3
4
5
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 |
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"
}'
2
3
4
5
6
7
8
9
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"
},
"ret_code":"000000",
"ret_msg":"success"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# ● 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'
2
3
4
5
6
7
Return example:
{
"respInfoList": [
{
"questionId": "2939578d354d4850a3d7b789dcb54caa",
"question": "what??",
"docId": "07a917c9b6734f65a1145a80a84e5e3f",
"highlight": "<font color='red'>what</font>??"
}
],
"originQuestion": "what"
}
2
3
4
5
6
7
8
9
10
11
# ● 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"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
Return example:
{
"item": {
"ustatus": "-1"
},
"ret_code": "000000",
"ret_msg": "success"
}
2
3
4
5
6
7
# 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."
}
2
3
4
# ● 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
2
3
4
5
6
# ● 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"
}
]}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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
}
2
3
4
# ● 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
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
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.