Developer Documentation Developer Documentation
Help Center (opens new window)
Help Center (opens new window)
  • Channel Access

    • Web Link Access Description
    • Web-JS Access Description
    • Android SDK
    • iOS SDK
    • WeChat Mini Program
    • Flutter、DCloud、APICloud
    • CRM Docking Scheme
  • Live Chat API
  • Chatbot API
    • Agent Component SDK

    • Message Push
    • Online Message Forwarding API
    • Knowledge Base V6 API
    • Chatbot Statistics API
    • Enterprise actively sends offline message API
    • Rule Engine API
    • AI Agent API
    • Text Product API
    Sobot
    2022-05-19
    Menus

    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:

    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
    
    1

    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/
    
    1

    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
    
    1

    Return example:

    {
        "item": {
            "token": "4ac37cb2e9c740dba4b75a34d5358802",
            "expires_in": "86400"
        },
        "ret_code": "000000",
        "ret_msg": "success"
    }
    
    1
    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
    
    1

    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"
    }'
    
    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!"
    }
    
    1
    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
    
    1

    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"
    						}
    					]
    				}
    
    1
    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"
    }
    
    1
    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"
    }
    
    1
    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"
    }
    
    1
    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"
    }
    
    1
    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"
    }
    
    1
    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
    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"
    }'
    
    1
    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",
            "special_msg_flag":1
        },
        "ret_code":"000000",
        "ret_msg":"success"
    }
    
    1
    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
    # ● 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
    
    1

    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'
    
    1
    2
    3
    4
    5
    6
    7

    Return example:

    {
        "respInfoList": [
            {
                "questionId": "2939578d354d4850a3d7b789dcb54caa",
                "question": "what??",
                "docId": "07a917c9b6734f65a1145a80a84e5e3f",
                "highlight": "<font color='red'>what</font>??"
            }
        ],
        "originQuestion": "what"
    }
    
    1
    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
    
    1

    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"
    }'
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14

    Return example:

    {
        "item": {
            "ustatus": "-1"
        },
        "ret_code": "000000",
        "ret_msg": "success"
    }
    
    1
    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.

    11

    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
    
    1

    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.

    12

    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?
    
    1

    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."   
    }
    
    1
    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.

    1

    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).

    2

    # ● Template pattern and param overview

    1.Template 1

    3

    4

    2.Template 2

    5

    6

    3.Template 3

    7

    8

    4.Template 4

    9

    10

    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.

    11

    # ● 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
    
    1
    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"
             }
         ]}
    
    1
    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
    }
    
    1
    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 
             }
         ]
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

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

    12

    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」.

    13

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

    14

    # 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.
    Last Updated: 4/2/2025, 8:17:54 PM

    ← Live Chat API Android SDK→

    Update Date
    01
    Operations Support API
    04-03
    02
    CRM Docking Scheme
    12-05
    03
    AI Agent API
    09-09
    More Articles>
    Theme by Vdoing
    • Follow Sys
    • Line
    • Dark
    • Read