Developer Documentation
  • Text Product API
Sobot
2024-09-09
Menus

AI Agent API

# Large-model bot

# 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, the unique API call credential ID for the 3rd-party users
create_time String Yes Timestamp (s), e.g.: timestamp 1569397773 for 2019-09-25 15:49:33
sign String Yes Signature, md5(appid + create_time + app_key) sign signature, app_key is private key

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
# ● Q&A - Streaming

API description:

API type: Active call API

API function: The answer can be obtained and a session can be established by calling this interface.

Request method:

POST

Request URL:

 http://sg.sobot.io/ai-agent-open/ask/answer
1

Request param

Name Location Type Required Description
body body OpenRobotAnswerReqVo Yes

OpenRobotAnswerReqVo

Name Type Required Description
question string yes Question
show_question string yes Display question
input_type_enum string yes Input type
biz_id string yes Business id
biz_type string yes Business line type
biz_type_id string yes Product id
robotid string yes Bot id
msg_type string yes TEXT, IMG
uid string false Visitor id
user_name string false Visitor name
transfer boolean false Whether to enable trans-to-agent
ai_agent_cid string false AiAgent chat id
call_back_url string false Callback URL
source_enum string yes Channel source
partnerid string false Docking id
params Map<String,Object> false Custom param
multi_params Map<String,Object> false Custom param
timing boolean false Whether to enable external timing
input_variable_infos OpenAnswerVariableInfo false Externally passed variable
process_info OpenProcessInfo false Enum variable click information
interface_info OpenInterfaceInfo false Node information
{
  "question": "Customer service",
  "show_question": "Customer service",
  "input_type_enum": "INPUT",
  "biz_id": "29967d81d67f4a708e8bd7d8f6356447",
  "biz_type": "TEXT",
  "msg_type": "TEXT", 
  "biz_type_id": "1000016",
  "robotid": "1",
  "uid": "c56844605e72633776a6de28d0f598f3",
  "user_name": "userName",
  "transfer": true,
  "ai_agent_cid": "12dec883b46d48a5808ea143379b7014",
  "call_back_url": "http://sg.sobot.io/aiAgent/callback",
  "source_enum": "PC",
  "partnerid": "123456",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": false,
  "input_variable_infos": [
    {
      "variable_id": "1888794111663644672",
      "variable_name": "variableName",
      "variable_value": "variableValue",
      "variable_type": "CHARACTER"
    }
  ],
  "process_info": {
    "process_id": "5a227ca7b4fc48e98d4e02b113c81c123",
    "node_id": "1905555364410802345",
    "variable_id": "1888794111663644672",
    "variable_value": "variableValue"
  },
  "interface_info": {
    "cardStyle": "0",
    "cardType": "1",
    "cardForm": "1",
    "cardGuide": "hello world",
    "customCards": [
      {
        "customCardName": {
          "variableId": "4a39e1872f1e427794848f30945dd50a",
          "paramValue": "mate70"
        },
        "customCardHeader": [
          {
            "no": {
              "variableId": null,
              "paramValue": "7"
            }
          }
        ],
        "customCardNum": null,
        "customField": [
          {
            "test": {
              "variableId": "4a39e1872f1e427794848f30945dd50a",
              "paramValue": "mate70"
            }
          }
        ],
        "customCardThumbnail": {
          "variableId": null,
          "paramValue": "https://img11.360buyimg.com/n5/s720x720_jfs/t1/332638/32/12246/51387/68c3817dFf6c2947b/3b00cd8ecfe6840b.jpg"
        },
        "customCardAmount": {
          "variableId": null,
          "paramValue": "5599"
        },
        "customCardAmountSymbol": null,
        "customCardDesc": {
          "variableId": null,
          "paramValue": "phone"
        },
        "customCardType": null,
        "customCardLink": null,
        "paramInfos": [
          {
            "variableId": "4a39e1872f1e427794848f30945dd50a",
            "paramValue": "meta70"
          }
        ],
        "customMenus": [
          {
            "menuType": 0,
            "menuName": "test",
            "menuLink": null
          }
        ]
      }
    ]
  }
}
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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

Return example

Succeeded

Return result

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

Return data data structure

Type Required Constraint Description
RobotAnswerRespVo yes none none

RobotAnswerRespVo

Name Type Required Description
robot_answer_type string yes Answer type
robot_answer_message_type string yes Message type
answer string false Answer
transfer_result string false Trans-to-agent result
roundid string yes Message round id
msgid string yes Message id
ai_agent_cid string yes AiAgent chat id
biz_id string yes Business id
robot_name string yes Bot name
robot_logo string yes Bot logo
robotid string yes Bot id
robot_status string yes Bot status
delay integer yes Node delay
output_variable_infos AnswerVariableInfo false Return collection variable
process_id string false Workflow id
node_id string false Node id
variable_id string false Variable id
variable_value_enums array false Enum list
interface_info OpenInterfaceInfo false Node information
{
  "data": [
    {
      "robot_answer_type": "QA_DIRECT",
      "robot_answer_message_type": "MESSAGE",
      "answer": "Customer service",
      "transfer_result": "NO_ACTION",
      "roundid": "12ef2d1957434f2eb4b45c629d2db2dc",
      "msgid": "12789cf50b784e4480a02289ddc69fb9",
      "ai_agent_cid": "12dec883b46d48a5808ea143379b7014",
      "biz_id": "29967d81d67f4a708e8bd7d8f6356447",
      "robot_name": "Ai-Agent",
      "robot_logo": "",
      "robotid": "1",
      "robot_status": "DELETE",
      "delay": 0,
      "output_variable_infos": [
        {
          "variable_id": "1888794111663644672",
          "variable_name": "variable_name",
          "variable_value": "variable_value",
          "variable_type": "CHARACTER"
        }
      ],
      "process_id": "5a227ca7b4fc48e98d4e02b113c81c123",
      "node_id": "1905555364410802345",
      "variable_id": "1888794111663644672",
      "variable_value_enums": [
        ""
      ],
      "interface_info": {
        "cardStyle": "1",
        "cardType": "1",
        "cardForm": "1",
        "cardGuide": "hello world",
        "customCards": [
          {
            "customCardName": {
              "variableId": "4a39e1872f1e427794848f30945dd50a",
              "paramValue": "mate70"
            },
            "customCardHeader": [
              {
                "no:": {
                  "variableId": null,
                  "paramValue": "7"
                }
              }
            ],
            "customCardNum": null,
            "customField": [
              {
                "test": {
                  "variableId": "4a39e1872f1e427794848f30945dd50a",
                  "paramValue": "mate70"
                }
              }
            ],
            "customCardThumbnail": {
              "variableId": null,
              "paramValue": "https://img11.360buyimg.com/n5/s720x720_jfs/t1/332638/32/12246/51387/68c3817dFf6c2947b/3b00cd8ecfe6840b.jpg"
            },
            "customCardAmount": {
              "variableId": null,
              "paramValue": "5599"
            },
            "customCardAmountSymbol": null,
            "customCardDesc": {
              "variableId": null,
              "paramValue": "phone"
            },
            "customCardType": null,
            "customCardLink": null,
            "paramInfos": [
              {
                "variableId": "4a39e1872f1e427794848f30945dd50a",
                "paramValue": "mate70"
              }
            ],
            "customMenus": [
              {
                "menuType": 0,
                "menuName": "test",
                "menuLink": null
              }
            ]
          }
        ]
      }
    }
  ],
  "retCode": "000000",
  "retMsg": "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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
# ● Q&A - Visitor side initialization

API description:

API type: Active call API

API function: Call this interface to initialize the visitor information and generate the visitor.

Request method:

GET

Request URL:

 http://sg.sobot.io/ai-agent-open/ask/ask_init
1

Request param

Name Location Type Required
robotid query string Yes
bizid query string Yes

Return example

Succeeded

{
  "data": {
    "bizid": "a97e877ad6b9403bbf945401ea331111",
    "ai_agent_cid": "17ad7f4ab65b4aedadb3b72caf6a86cd",
    "biz_type": "AI_AGENT",
    "biz_typeid": "1000045"
  },
  "retCode": "000000",
  "retMsg": "success"
}
1
2
3
4
5
6
7
8
9
10

Return result

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

Return data structure

InitRespVo

Type Required Constraint Description
InitRespVo yes none none

Attribute

Name Type Required Description
bizId string¦null false Business id
aiAgentCid string¦null false Current chat id
bizType string¦null false Business line type
bizTypeId string¦null false Product id
{
  "bizId": "a97e877ad6b9403bbf945401ea331111",
  "aiAgentCid": "17ad7f4ab65b4aedadb3b72caf6a86cd",
  "bizType": "AI_AGENT",
  "bizTypeId": "1000045"
}
1
2
3
4
5
6
7
# ● Q&A - Non-streaming

API description:

API type: Active call API

API function: The answer can be obtained and a session can be established by calling this interface.

Request method:

POST

Request URL:

 http://sg.sobot.io/ai-agent-open/ask/answer_no_stream
1

Body request param

Request param

Name Location Type Required Description
body body OpenRobotAnswerReqVo Yes none

OpenRobotAnswerReqVo

Name Type Required Description
question string yes Question
show_question string yes Display question
input_type_enum string yes Input type
biz_id string yes Business id
biz_type string yes Business line type
biz_type_id string yes Product id
robotid string yes Bot id
msg_type string yes TEXT, IMG
uid string false Visitor id
user_name string false Visitor name
transfer boolean false Whether to enable trans-to-agent
ai_agent_cid string false AiAgent chat id
call_back_url string false Callback URL
source_enum string yes Channel source
partnerid string false Docking id
params Map<String,Object> false Custom param
multi_params Map<String,Object> false Custom param
timing boolean false Whether to enable external timing
input_variable_infos OpenAnswerVariableInfo false Externally passed variable
process_info OpenProcessInfo false Enum variable click information
interface_info OpenInterfaceInfo false Node information
{
  "question": "Customer service",
  "show_question": "Customer service",
  "input_type_enum": "INPUT",
  "biz_id": "a97e877ad6b9403bbf945401ea331111",
  "biz_type": "TEXT",
  "msg_type": "TEXT",
  "biz_type_id": "1000016",
  "robotid": "1",
  "uid": "c56844605e72633776a6de28d0f598f3",
  "user_name": "userName",
  "transfer": true,
  "ai_agent_cid": "17ad7f4ab65b4aedadb3b72caf6a86cd",
  "call_back_url": "http://www.sobot.com/aiAgent/callback",
  "source_enum": "PC",
  "partnerid": "123456",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": false,
  "input_variable_infos": [
    {
      "variable_id": "1888794111663644672",
      "variable_name": "variableName",
      "variable_value": "variableValue",
      "variable_type": "CHARACTER"
    }
  ],
  "process_info": {
    "process_id": "5a227ca7b4fc48e98d4e02b113c81c123",
    "node_id": "1905555364410802345",
    "variable_id": "1888794111663644672",
    "variable_value": "variableValue"
  }
}
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

Return example

Succeeded

Return result

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

Return data data structure

Type Required Constraint Description
RobotAnswerRespVo yes none none
{
  "data": [
    {
      "robot_answer_type": "QA_DIRECT",
      "robot_answer_message_type": "MESSAGE",
      "answer": "Customer service",
      "transfer_result": "NO_ACTION",
      "roundid": "12ef2d1957434f2eb4b45c629d2db2dc",
      "msgid": "12789cf50b784e4480a02289ddc69fb9",
      "ai_agent_cid": "12dec883b46d48a5808ea143379b7014",
      "biz_id": "29967d81d67f4a708e8bd7d8f6356447",
      "robot_name": "Ai-Agent",
      "robot_logo": "",
      "robotid": "1",
      "robot_status": "DELETE",
      "delay": 0,
      "output_variable_infos": [
        {
          "variable_id": "1888794111663644672",
          "variable_name": "variableName",
          "variable_value": "variableValue",
          "variable_type": "CHARACTER"
        }
      ],
      "process_id": "5a227ca7b4fc48e98d4e02b113c81c123",
      "node_id": "1905555364410802345",
      "variable_id": "1888794111663644672",
      "variable_value_enums": [
        ""
      ]
    }
  ],
  "retCode": "000000",
  "retMsg": "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
# ● Q&A - Word association

API description:

API type: Active call API

API function: Customers can obtain the questions in the knowledge base in advance through this interface.

Request method:

POST

Request URL:

 http://sg.sobot.io/ai-agent-open/ask/answer_suggest
1

Body request param

Request param

Name Location Type Required Description
body body RobotAnswerReqVo Yes none

RobotAnswerReqVo

Name Type Required Description
question string yes Question
show_question string yes Display question
input_type_enum string yes Input type
biz_id string yes Business id
biz_type string yes Business line type
biz_type_id string yes Product id
robotid string yes Bot id
msg_type string yes TEXT, IMG
uid string false Visitor id
user_name string false Visitor name
transfer boolean false Whether to enable trans-to-agent
ai_agent_cid string false AiAgent chat id
call_back_url string false Callback URL
source_enum string yes Channel source
partnerid string false Docking id
params Map<String,Object> false Custom param
multi_params Map<String,Object> false Custom param
timing boolean false Whether to enable external timing
input_variable_infos OpenAnswerVariableInfo false Externally passed variable
process_info OpenProcessInfo false Enum variable click information
{
  "question": "Customer service",
  "show_question": "Customer service",
  "input_type_enum": "INPUT",
  "biz_id": "29967d81d67f4a708e8bd7d8f6356447",
  "biz_type": "TEXT",
  "msg_type": "TEXT",
  "biz_type_id": "1000016",
  "robotid": "1",
  "uid": "c56844605e72633776a6de28d0f598f3",
  "user_name": "userName",
  "transfer": true,
  "ai_agent_cid": "12dec883b46d48a5808ea143379b7014",
  "call_back_url": "http://www.sobot.com/aiAgent/callback",
  "source_enum": "PC",
  "partnerid": "123456",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": false,
  "input_variable_infos": [
    {
      "variable_id": "1888794111663644672",
      "variable_name": "variableName",
      "variable_value": "variableValue",
      "variable_type": "CHARACTER"
    }
  ]
}
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

Return example

Succeeded

Return result

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

Return data data structure

Type Required Constraint Description
RobotAnswerSuggestRespVo yes none none
{
  "data": {
    "qa_contents": [
      {
        "question": "Customer service",
        "questionid": "dda6a07ef5b74642a601102095d1681a",
        "docid": "e3e8a0a11f27496a8448ced8a7ba392d",
        "score": 0
      }
    ]
  },
  "retCode": "000000",
  "retMsg": "success"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# ● Q&A - Asynchronous

API description:

API type: Active call API

API function: The robot's answer can be returned asynchronously by calling this interface.

Request method:

POST

Request URL:

 http://sg.sobot.io/ai-agent-open/ask/answer_with_call_back
1

Body request param

Request param

Name Location Type Required Description
body body RobotAnswerReqVo Yes none
{
  "question": "Customer service",
  "show_question": "Customer service",
  "input_type_enum": "INPUT",
  "biz_id": "29967d81d67f4a708e8bd7d8f6356447",
  "biz_type": "TEXT",
  "msg_type": "TEXT",
  "biz_type_id": "1000016",
  "robotid": "1",
  "uid": "c56844605e72633776a6de28d0f598f3",
  "user_name": "userName",
  "transfer": true,
  "ai_agent_cid": "12dec883b46d48a5808ea143379b7014",
  "call_back_url": "http://www.sobot.com/aiAgent/callback",
  "source_enum": "PC",
  "partnerid": "123456",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": "false",
  "input_variable_infos": [
    {
      "variable_id": "1888794111663644672",
      "variable_name": "variableName",
      "variable_value": "variableValue",
      "variable_type": "CHARACTER"
    }
  ],
  "process_info": {
    "process_id": "5a227ca7b4fc48e98d4e02b113c81c123",
    "node_id": "1905555364410802345",
    "variable_id": "1888794111663644672",
    "variable_value": "variableValue"
  }
}
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

Return example

Succeeded

{
  "data": {},
  "retCode": "000000",
  "retMsg": "success",
  "pageNo": 0,
  "pageCount": 0,
  "totalCount": 0,
  "pageSize": 0
}
1
2
3
4
5
6
7
8
9

Return result

Param Type Required Description
ret_code String Yes Return code
ret_msg String Yes Return message
data Object No Return object
# ● Chat end

API description:

API type: Active call API

API function: The session of the robot can be ended by calling this interface.

Request method:

GET

Request URL:

 http://sg.sobot.io/ai-agent-open/ask/end_session
1

Request param

Name Location Type Required Description
ai_agent_cid query string Yes none

Return example

Succeeded

{
  "data": {},
  "ret_code": "000000",
  "ret_msg": "success"
}
1
2
3
4
5

Return result

Param Type Required Description
ret_code String Yes Return code
ret_msg String Yes Return message
data Object No Return object
# ● Polling timeout message

API description:

API type: Active call API

API function: The timeout message can be polled by calling this interface.

Request method:

GET

Request URL:

 http://sg.sobot.io/ai-agent-open/ask/get_push_info
1

Request param

Name Location Type Required Description
msgid query string Yes none

Return example

Succeeded

{
  "data": {
    "msgid": "12789cf50b784e4480a02289ddc69fb9",
    "data": {
      "msgid": "12789cf50b784e4480a02289ddc69fb9",
      "bizid": "a97e877ad6b9403bbf945401ea331111",
      "ai_agent_cid": "12dec883b46d48a5808ea143379b7014",
      "round_id": "12ef2d1957434f2eb4b45c629d2db2dc",
      "msg": "Customer service",
      "source_enum": "PC",
      "uid": "c56844605e72633776a6de28d0f598f3",
      "polling_id": "4cd268c9836d45eb931af9c70cf6cc1d",
      "polling_status": "POLLING_END"
    },
    "bizid": "a97e877ad6b9403bbf945401ea331111",
    "push_type": "ROBOT_ANSWER"
  },
  "retCode": "000000",
  "retMsg": "success"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Return result

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

Return data data structure

Type Required Constraint Description
PushInfo<PushData> yes none none
# ● Q&A - Integration With Third-party AI Agents

API Description: Customers can use it by configuring the corresponding address on the AI agent configuration page.

API Type: Proactive Call API

API Function: Sobot's large model can directly obtain the answer from the customer's large model through this API.

Request method:

POST

Request URL: Configured by the customer themselves

Body request param

Request param

Name Location Type Required Description
body body ThirdAlgorithmReqVo Yes

ThirdAlgorithmReqVo Object:

Name Type Required Description
question string Yes Question
show_question string Yes Display question
input_type_enum string Yes Input type: INPUT-Normal input, CLICK-Normal click, PROCESS_CLICK-Task workflow click, PROCESS_CARD_CLICK-Multi-round card click
robot_name string No Bot name
robotLogo string No Bot logo
robotRemark string No Bot remark
robotid string Yes Bot ID
msg_type string Yes TEXT: Text, IMG: Image
companyid string Yes Company ID
biz_type string Yes Business line type: TEXT-Text, CALL-Call, WORK_ORDER-Ticket
partnerid string No Partner ID
ai_agent_cid string Yes AiAgentChat ID
interface_info ThirdInterfaceInfo No Node card API information
source_enum string No Channel source
context_validity_time Long Yes Context validity time
params Map<String,Object> No Custom parameters
multi_params Map<String,Object> No Custom parameters
roundid string Yes Round ID
input_variable_infos OpenAnswerVariableInfo No External input variables
process_info OpenProcessInfo No Enum variable click information
runtimeid string No Runtime ID, used for batch testing
questionid string No Batch test question ID
robot_model string Yes Bot mode: THIRD_STANDARD-Standard, THIRD_DEBUG-Debug
req_stream boolean Yes Request AI return format: true-Streaming, false-Standard HTTP
copilot boolean Yes Whether it is a copilot bot: true-Yes, false-No

ThirdInterfaceInfo Object:

Name Type Required Description
card_style string Yes Card style, 1-List
card_type string Yes Card type, 1-Product
card_form string Yes Card source, 1-Large model
card_guide string Yes Card guiding phrase
custom_cards List Yes Card information

ThirdInterfaceCardInfo Object:

Name Type Required Description
custom_card_name ThirdCardParamInfo Yes Title
custom_card_header List<Map<String, ThirdCardParamInfo>> No Header
custom_card_num ThirdCardParamInfo No Product quantity
custom_field List<Map<String, ThirdCardParamInfo>> No Custom fields of the card
custom_card_thumbnail ThirdCardParamInfo No Image
custom_card_amount ThirdCardParamInfo No Total amount
custom_card_amount_symbol ThirdCardParamInfo No Currency symbol
custom_card_desc ThirdCardParamInfo No Description
custom_card_type Integer Yes Card action type, 0-Send, 1-Custom
custom_card_link String No Card link
param_infos List No The mapping relationship between all params and variables of this card
custom_menus ThirdInterfaceCardButtonInfo No Card button

ThirdInterfaceCardButtonInfo Object:

Name Type Required Description
menu_type Integer Yes Button action type, 0-Send, 1-Custom
menu_name String Yes Button name
menu_link String No Button link
{
   "question": "question_7a033c05b97d",
   "show_question": "show_question_a8e88791853d",
   "input_type_enum": "INPUT",
   "robotid": "robotid_97775fd863d0",
   "robot_name": "robot_name_fb9b23e26933",
   "robot_logo": "robot_logo_dbf190cab17c",
   "robot_remark": "robot_remark_e860b23dd59a",
   "ai_agent_cid": "ai_agent_cid_ad877ac21893",
   "companyid": "companyid_69c0a98e2874",
   "biz_type": "TEXT",
   "context_validity_time": 0,
   "partnerid": "partnerid_657958dce1b1",
   "params": {},
   "multi_params": {},
   "source_enum": "source_enum_8226cdbd3c71",
   "roundid": "roundid_5da5d19a0f2d",
   "input_variable_infos": [
      {
         "variable_id": "variable_id_9acd68d03618",
         "variable_name": "variable_name_97abb8c7029d",
         "variable_value": "variable_value_17c2da4c71d3",
         "variable_code": "variable_code_da936fee5e9f",
         "variable_type": "CHARACTER"
      }
   ],
   "process_info": {
      "node_id": "node_id_00afb01de3f6",
      "process_id": "process_id_4af01bd3b25e",
      "variable_id": "variable_id_9f732319c7ea",
      "variable_value": "variable_value_ffb2e58773f6"
   },
   "interface_info": {
      "card_style": "card_style_e9938c7cc17b",
      "card_type": "card_type_01210c33f5d2",
      "card_form": "card_form_59c9037b1546",
      "card_guide": "card_guide_02e0d57211c7",
      "custom_cards": [
         {
            "custom_card_name": {
               "variableid": "variableid_3b06f96fe2c8",
               "param_value": "param_value_87ceefad6dc2"
            },
            "custom_card_header": [
               {}
            ],
            "custom_card_num": {
               "variableid": "variableid_161a64d8e3e5",
               "param_value": "param_value_a493dcf0d81d"
            },
            "custom_field": [
               {}
            ],
            "custom_card_thumbnail": {
               "variableid": "variableid_a3c2d8153b2e",
               "param_value": "param_value_5e12a18d6a85"
            },
            "custom_card_amount": {
               "variableid": "variableid_2037358e2a11",
               "param_value": "param_value_bce35b73feb0"
            },
            "custom_card_amount_symbol": {
               "variableid": "variableid_93e1ae7feee2",
               "param_value": "param_value_d0e53f4fa478"
            },
            "custom_card_desc": {
               "variableid": "variableid_4a6d6a88f707",
               "param_value": "param_value_e34a1576d661"
            },
            "custom_card_type": 0,
            "custom_card_link": "custom_card_link_7d98c985f4f9",
            "param_infos": [
               {
                  "variableid": "variableid_4e163ff134c0",
                  "param_value": "param_value_dbf47baf0341"
               }
            ],
            "custom_menus": [
               {
                  "menu_type": 0,
                  "menu_name": "menu_name_7a4c7b514a8e",
                  "menu_link": "menu_link_062f16821e30"
               }
            ]
         }
      ]
   },
   "msg_type": "TEXT",
   "runtimeid": "runtimeid_82de6047a003",
   "questionid": "questionid_b89f6d5dd01b",
   "robot_model": "SELF_DEBUG",
   "req_stream": false,
   "copilot": false
}
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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

Return Example

Success

Return result

param Type Required Description
ret_code String Yes Return code
ret_msg String Yes Return message
data Object No Return object

Return data structure

Type Required Constraints Description
ThirdAlgorithmRespVo Yes none none

ThirdAlgorithmRespVo

Name Type Required Description
answer_type string Yes Answer type
robot_answer_message_type string Yes Message type: THIRD_ANSWER_INFO-text or non-process, THIRD_PROCESS_INFO-task workflow, MESSAGE-text message (not appear alone)
lan string Yes Language identifier
llm_answer string Yes Answer
roundid string Yes Message round id
runtimeid string No Batch test run id
questionid string No Batch test question id
companyid string Yes Company id
success boolean No Batch test algorithm flag, true: success, false: failure
hit_sensitive_word boolean No Hit sensitive word
message_end string Yes Last message of MESSAGE
third_interface_info ThirdInterfaceInfo No Card message body
third_processid string No Third-party process id
third_nodeid string No Third-party node id
third_variable_value_enums List No Third-party variable id
third_variable_id String No Third-party variable set
{
   "answer_type": "QA_DIRECT",
   "robot_answer_message_type": "MESSAGE",
   "lan": "lan_8018cad1eccd",
   "llm_answer": "llm_answer_f04380c77ff6",
   "roundid": "roundid_0aa8febbcca7",
   "runtimeid": "runtimeid_b80f48e55d61",
   "questionid": "questionid_8536deb2a29a",
   "companyid": "companyid_770644147cec",
   "success": false,
   "hit_sensitive_word": false,
   "message_end": false,
   "third_interface_info": {
      "card_style": "card_style_7c284829f017",
      "card_type": "card_type_bf7ff998f8a4",
      "card_form": "card_form_79314e2b5755",
      "card_guide": "card_guide_46d88ed54b29",
      "custom_cards": [
         {
            "custom_card_name": {
               "variableid": "variableid_1e5238bb6165",
               "param_value": "param_value_772bde60287e"
            },
            "custom_card_header": [
               {}
            ],
            "custom_card_num": {
               "variableid": "variableid_bdb40ee8ef87",
               "param_value": "param_value_9e958a35826b"
            },
            "custom_field": [
               {}
            ],
            "custom_card_thumbnail": {
               "variableid": "variableid_65808769c6f5",
               "param_value": "param_value_14dbe5a13f6c"
            },
            "custom_card_amount": {
               "variableid": "variableid_4ddf5bc95e1e",
               "param_value": "param_value_c0170efe1283"
            },
            "custom_card_amount_symbol": {
               "variableid": "variableid_99b9b4dba216",
               "param_value": "param_value_1ffd443bc8a8"
            },
            "custom_card_desc": {
               "variableid": "variableid_6bacee5947e0",
               "param_value": "param_value_a94494bc11ea"
            },
            "custom_card_type": 0,
            "custom_card_link": "custom_card_link_35b8326a91f9",
            "param_infos": [
               {
                  "variableid": "variableid_2b27893622b1",
                  "param_value": "param_value_ca7bda6d2f9f"
               }
            ],
            "custom_menus": [
               {
                  "menu_type": 0,
                  "menu_name": "menu_name_ddb1ea945dbc",
                  "menu_link": "menu_link_bfba26affa51"
               }
            ]
         }
      ]
   },
   "third_processid": "third_processid_eb483c5b915e",
   "third_nodeid": "third_nodeid_8870ffb96e8d",
   "third_variable_value_enums": [
      "third_variable_value_enums_3135b9f69643"
   ],
   "third_variable_id": "third_variable_id_47a7e93cf55b"
}
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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
# ● Q&A - Callback For Assisted Types In Third-party AI Agent Integration

API Description: When calling the customer's AI agent, if copilot=true, the customer needs to actively call back Sobot and pass in the answer.

API Type: Passive Call API

API Function: Used for customers to return answers

Request Method:

POST

Request Address:

https://api-c.soboten.com/text/ai-agent-open/ask/callback_list
1

Body request param

Request param

Name Location Type Required Description
body body ThirdCallbackListRespVo Yes

ThirdCallbackListRespVo Object:

Name Type Required Description
algorithm_resp_vos List Yes Algorithm response

Return Example

Success

# ● Q&A - Batch Testing Callback For Third-party AI Agent Integration

API Description: When calling the customer's AI agent, if runtimeId is not empty, the customer needs to actively call back Sobot and pass in the test results.

API Type: Passive Call API

API Function: Customers can use this API to notify Sobot of the test results.

Request method:

POST

Request URL:

https://api-c.soboten.com/text/ai-agent-open/api/kb/question_call_back
1

Body request param

Request param

Name Location Type Required Description
body body ThirdAlgorithmRespVo Yes

Return example

Success

# ● Streaming API parsing method
  1. Determine that the robotAnswerMessageType field ERROR_END indicates an abnormal end to the chat, and MESSAGE indicates message parsing; extract the answer field directly, with msgId corresponding to the message id and the information below. ANSWER_INFO and PROCESS_INFO are for answer information parsing; both answer and the other fields need to be parsed, and if answer has no value, no parsing is needed.
  2. Determine the robotAnswerType field; in the cases of ANSWER_INFO and PROCESS, this field is currently used for displaying the trans-to-agent button, and it may have other purposes in the future.
  3. Determine the transferResult field; in the cases of ANSWER_INFO and PROCESS, this field is used to determine whether trans-to-agent is needed.
  4. Determine the delay field; in the cases of ANSWER_INFO and PROCESS, if this field is greater than 0, polling node timeout will be initiated
# ● Button message interaction in task workflow
  1. The variable in the workflow is set as an enum type
  2. The bot Q&A API output param RobotAnswerRespVo will return enum related data (process_id, node_id, variable_id, variable_value_enums)
  3. After selecting a value from the enum, the bot Q&A API input param RobotAnswerReqVo needs to add enum data process_info (process_id corresponds to process_id in step 2, node_id corresponds to node_id in step 2, variable_id corresponds to variable_id in step 2, variable_value corresponds to a certain value in variable_value_enums in step 2), and input_type_enum is set to PROCESS_CLICK
# ● Task Flow Node Message Interaction
  1. Relevant card messages are configured in the process.
  2. The robot Q&A interface output parameter RobotAnswerRespVo will return relevant card message data (interface_info).
  3. When a card message is clicked, the card data (interface_info) needs to be added to the input parameter RobotAnswerReqVo of the robot Q&A interface. Specific modifications to the input parameter values:
Param Type Description
input_type_enum String PROCESS_CARD_CLICK
interface_info Object See：Interface_info Description
show_question String See: show_question description, pass as a string parameter.
question String See: question description, pass as a string parameter.

Interface_info Description

The interface_info field processes the returned interface_info object and then uses it as a parameter.
1. Set the cardStyle in interface_info to 0.
2. Use the entire modified interface_info object as the parameter for the interface_info field.
1
2
3

Show_question Description

The show_question field processes the returned interface_info field and then uses it as a parameter.
1. Set the cardStyle in interface_info to 0.
2. For the customCards field, keep only the complete attributes of the clicked card as the parameter.
3. Leave other fields unchanged, and then use it as a string format parameter.

Example: {\"cardStyle\":\"0\",\"cardType\":\"1\",\"cardForm\":\"1\",\"cardGuide\":\"hello world\",\"customCards\":[{\"customCardName\":{\"variableId\":\"123\",\"paramValue\":\"meta70\"},\"customCardHeader\":[{\"no:\":{\"variableId\":null,\"paramValue\":\"1\"}}],\"customCardNum\":null,\"customField\":[{\"info:\":{\"variableId\":\"789\",\"paramValue\":\"meta70\"}}],\"customCardThumbnail\":{\"variableId\":null,\"paramValue\":\"https://A.jpg\"},\"customCardAmount\":{\"variableId\":null,\"paramValue\":\"3999\"},\"customCardAmountSymbol\":null,\"customCardDesc\":{\"variableId\":null,\"paramValue\":\"phone\"},\"customCardType\":null,\"customCardLink\":null,\"paramInfos\":[{\"variableId\":null,\"paramValue\":\"1\"},{\"variableId\":\"456\",\"paramValue\":\"meta70\"},{\"variableId\":null,\"paramValue\":\"3999\"},{\"variableId\":null,\"paramValue\":\"phone\"},{\"variableId\":null,\"paramValue\":\"https://A.jpg\"}],\"customMenus\":[{\"menuType\":0,\"menuName\":\"test\",\"menuLink\":null}]}]}
1
2
3
4
5
6

Question Description

The question field needs to be assembled as follows:
1. Extract the paramInfos attribute from the clicked card.
2. Loop through the paramInfos array.
3. Assemble an object with the following parameters:
processId : data.processId,
nodeId : data.nodeId,
variableId : paramInfos[i].variableId,
variableValue : paramInfos[i].paramValue
customCardButtonName: The name of the clicked button, customMenus.menuName
4. Add the assembled object to a collection after looping.
5. Format the current collection as a string for input.

Example: [{\"processId\":\"123\",\"nodeId\":\"456\",\"variableId\":null,\"variableValue\":\"3\",\"customCardButtonName\":\"test\"}]
1
2
3
4
5
6
7
8
9
10
11
12
13
# ● Third-party API Integration for Large Models

[Output Requirement] Only provide the translation result, without comments/explanations.

  1. Check the input_type_enum field: INPUT - Normal input, CLICK - Normal click, PROCESS_CLICK - Task workflow click, PROCESS_CARD_CLICK - Multi-round card click
    INPUT: Directly use question as the question to ask
    CLICK: Reserved
    PROCESS_CLICK: Button mode click in task workflow, process_info will be passed in as a parameter and the click information will be transmitted
    PROCESS_CARD_CLICK: Card mode click in task workflow, interface_info will be passed in as a parameter and the click information will be transmitted
  2. Check the msg_type field: TEXT is plain text, or when input_type_enum=PROCESS_CLICK/PROCESS_CARD_CLICK, question is JSON; IMG is an image, and question contains a link
  3. Check the robot_model field: Select the appropriate answer based on whether it is standard or debugging
  4. Check the req_stream field: When true, return data in sse format as a stream, refer to Streaming API Parsing Method for specific return method, where PROCESS_INFO is replaced with THIRD_PROCESS_INFO, and ANSWER_INFO is replaced with THIRD_ANSWER_INFO
    When MESSAGE, set message_end=true for the last MESSAGE in this answer
    When false, return all data at once in standard http format, refer to Q&A - Non-streaming, with the startup data format as List
  5. Check the copilot field: When true, call the Q&A - Third-party AI Agent Assisted Callback API to transmit the answer back
  6. Check the runtimeid field: When not empty, call the Q&A - Third-party AI Agent Batch Test Callback API to transmit the result back
  7. Roundid is the round ID, one round per Q&A session, carry it over when asking the question and return it when providing the answer
# ● Data model

PushInfo

{
  "msgid": "12789cf50b784e4480a02289ddc69fb9",
  "data": {},
  "bizid": "a97e877ad6b9403bbf945401ea331111",
  "push_type": "SESSION_OVER_TIME"
}
1
2
3
4
5
6
7

Attribute

Name Type Required Description
msg_id string yes Message id
data Object yes Message
bizid string yes Business id
push_type string yes Message type

PushData format

{
  "msgid": "12789cf50b784e4480a02289ddc69fb9",
  "bizid": "a97e877ad6b9403bbf945401ea331111",
  "ai_agent_cid": "12dec883b46d48a5808ea143379b7014",
  "round_id": "12ef2d1957434f2eb4b45c629d2db2dc",
  "msg": "Customer service",
  "source_enum": "PC",
  "uid": "c56844605e72633776a6de28d0f598f3",
  "polling_id": "4cd268c9836d45eb931af9c70cf6cc1d",
  "polling_status": "POLLING_END"
}
1
2
3
4
5
6
7
8
9
10
11

Attribute

Name Type Required Description
msgid string yes Message id
bizid string yes Business id
ai_agent_cid string yes Large-model bot chat id
round_id string yes Round id
msg string false Message
source_enum string yes Source
uid string false Visitor id
polling_id string yes Polling id
polling_status string yes Polling status

Enum value

Attribute Value Description
push_type SESSION_OVER_TIME Chat timeout, data format
push_type NODE_OVER_TIME Node timeout, data format
push_type ROBOT_ANSWER Push answer, data data is List<RobotAnswerRespVo>
polling_status POLLING_START Start
polling_status POLLING_RUNNING Ongoing
polling_status POLLING_END End

RobotAnswerReqVo

{
  "question": "Customer service",
  "show_question": "Customer service",
  "input_type_enum": "INPUT",
  "biz_id": "29967d81d67f4a708e8bd7d8f6356447",
  "biz_type": "TEXT",
  "biz_type_id": "1000016",
  "robotid": "1",
  "uid": "c56844605e72633776a6de28d0f598f3",
  "user_name": "userName",
  "transfer": true,
  "ai_agent_cid": "12dec883b46d48a5808ea143379b7014",
  "call_back_url": "http://www.sobot.com/aiAgent/callback",
  "source_enum": "PC",
  "partnerid": "123456",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": false,
  "input_variable_infos": [
    {
      "variable_id": "1888794111663644672",
      "variable_name": "variableName",
      "variable_value": "variableValue",
      "variable_type": "CHARACTER"
    }
  ],
  "process_info": {
    "process_id": "5a227ca7b4fc48e98d4e02b113c81c123",
    "node_id": "1905555364410802345",
    "variable_id": "1888794111663644672",
    "variable_value": "variableValue"
  }
}
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

Attribute

Name Type Required Description
question string yes Question
show_question string yes Display question
input_type_enum string yes Input type
biz_id string yes Business id
biz_type string yes Business line type
biz_type_id string yes Product id
robotid string yes Bot id
uid string false Visitor id
user_name string false Visitor name
transfer boolean false Whether to enable trans-to-agent
ai_agent_cid string false AiAgent chat id
call_back_url string false Callback URL
source_enum string yes Channel source
partnerid string false Docking id
params Map<String,Object> false Custom param
multi_params Map<String,Object> false Custom param
timing boolean false Whether to enable external timing
input_variable_infos OpenAnswerVariableInfo false Externally passed variable
process_info OpenProcessInfo false Enum variable click information

Enum value

Attribute Value Description
input_type_enum INPUT Normal input
input_type_enum CLICK Click input
input_type_enum PROCESS_CLICK Task process click input
input_type_enum WELCOME Get welcome message
input_type_enum PROCESS_CARD_CLICK Task Workflow Card Input
biz_type AI_AGENT Large-model bot itself
source_enum PC Desktop
source_enum weChat WeChat
source_enum APP sdk
source_enum weiBo Weibo
source_enum wap h5
source_enum huJiao Call
source_enum workOrder Ticket
source_enum uCenter CRM
source_enum qiYeWeixin WeCom
source_enum miniApp Mini Program
source_enum baiDu Baidu
source_enum touTiao Taobao
source_enum qihu360 Qihoo 360
source_enum wolongShenMa
source_enum sougou SoGou
source_enum wxkf WeChat Agent
source_enum guangDianTong
source_enum zhihu
source_enum fb
source_enum whatsApp
source_enum instagram
source_enum line
source_enum discord
source_enum telegram
source_enum shopify
source_enum twitter

AnswerVariableInfo

{
  "variable_id": "1888794111663644672",
  "variable_name": "variableName",
  "variable_value": "variableValue",
  "variable_code": "string",
  "variable_type": "CHARACTER"
}
1
2
3
4
5
6
7

Attribute

Name Type Required Description
variable_id string yes Variable id
variable_name string yes Variable name
variable_value string yes Variable value
variable_code string yes Variable code
variable_type string yes Variable type (1: Char, 2: Number, 3: Enum)

Enum value

Attribute Value Description
variable_type CHARACTER Chars
variable_type NUMBER Number
variable_type ENUMERATION Enum

OpenProcessInfo

{
  "process_id": "5a227ca7b4fc48e98d4e02b113c81c123",
  "node_id": "1905555364410802345",
  "variable_id": "1888794111663644672",
  "variable_value": "variableValue"
}
1
2
3
4
5
6
7

Attribute

Name Type Required Description
variable_id string yes Variable id
process_id string yes Workflow id
variable_value string yes Variable value
node_id string yes Node id

OpenInterfaceInfo

{
   "cardStyle": "0",
   "cardType": "1",
   "cardForm": "1",
   "cardGuide": "hello",
   "customCards": [
      {
         "customCardName": {
            "variableId": "4a39e1872f1e427794848f30945dd50a",
            "paramValue": "mate70"
         },
         "customCardHeader": [
            {
               "no:": {
                  "variableId": null,
                  "paramValue": "7"
               }
            }
         ],
         "customCardNum": null,
         "customField": [
            {
               "test:": {
                  "variableId": "4a39e1872f1e427794848f30945dd50a",
                  "paramValue": "mate70"
               }
            }
         ],
         "customCardThumbnail": {
            "variableId": null,
            "paramValue": "https://img11.360buyimg.com/n5/s720x720_jfs/t1/332638/32/12246/51387/68c3817dFf6c2947b/3b00cd8ecfe6840b.jpg"
         },
         "customCardAmount": {
            "variableId": null,
            "paramValue": "5599"
         },
         "customCardAmountSymbol": null,
         "customCardDesc": {
            "variableId": null,
            "paramValue": "phone"
         },
         "customCardType": null,
         "customCardLink": null,
         "paramInfos": [
            {
               "variableId": "4a39e1872f1e427794848f30945dd50a",
               "paramValue": "mate70"
            }
         ],
         "customMenus": [
            {
               "menuType": 0,
               "menuName": "test",
               "menuLink": null
            }
         ]
      }
   ]
}
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
50
51
52
53
54
55
56
57
58
59

Object

Name Type Required Description
cardStyle string yes Card style, 1 is the card list sent by the bot, and 0 is the response card clicked by the customer.
cardType string yes Card type, 1-Product
cardForm string yes Card source, 1-Large Model
cardGuide string yes Card Guidance Message
customCards List yes Card Information

OpenInterfaceCardInfo Object

Name Type Required Description
customCardName OpenCardParamInfo yes Title
customCardHeader List<Map<String, OpenCardParamInfo>> false Header
customCardNum OpenCardParamInfo false Quantity of Goods
customField List<Map<String, OpenCardParamInfo>> false Custom Fields for Cards
customCardThumbnail OpenCardParamInfo false Image
customCardAmount OpenCardParamInfo false Total Amount
customCardAmountSymbol OpenCardParamInfo false Currency Symbol
customCardDesc OpenCardParamInfo false Description
customCardType Integer false Card action type, 0-Send, 1-Custom
customCardLink String false Card Link
paramInfos List false The mapping of all params and variables for this card.
customMenus List false Card Button

OpenCardParamInfo Object

Name Type Required Description
variableId string false Variable id
paramValue string false Value

OpenInterfaceCardButtonInfo Object

Name Type Required Description
menuType string false Button action type, 0-Send, 1-Custom
menuName string false Button Name
menuLink string false Button Link

QaInfo

{
  "question": "Customer service",
  "questionid": "dda6a07ef5b74642a601102095d1681a",
  "docid": "e3e8a0a11f27496a8448ced8a7ba392d",
  "score": 0
}
1
2
3
4
5
6
7

Attribute

Name Type Required Description
question string yes Standardized question
questionId string yes Standardized question id
docId string yes Entry id
score number yes Matching threshold

RobotAnswerSuggestRespVo

{
  "qa_contents": [
    {
      "question": "Customer service",
      "questionid": "string",
      "docid": "e3e8a0a11f27496a8448ced8a7ba392d",
      "score": 0
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11

Attribute

Name Type Required Description
qaContents QaInfo yes Word association list

RobotAnswerRespVo

{
  "robot_answer_type": "QA_DIRECT",
  "robot_answer_message_type": "MESSAGE",
  "answer": "Customer service",
  "transfer_result": "NO_ACTION",
  "roundid": "12ef2d1957434f2eb4b45c629d2db2dc",
  "msgid": "12789cf50b784e4480a02289ddc69fb9",
  "ai_agent_cid": "12dec883b46d48a5808ea143379b7014",
  "biz_id": "29967d81d67f4a708e8bd7d8f6356447",
  "robot_name": "Ai-Agent",
  "robot_logo": "string",
  "robotid": "1",
  "robot_status": "DELETE",
  "delay": 0,
  "output_variable_infos": [
    {
      "variable_id": "1888794111663644672",
      "variable_name": "variableName",
      "variable_value": "variableValue",
      "variable_code": "string",
      "variable_type": "CHARACTER"
    }
  ],
  "process_id": "5a227ca7b4fc48e98d4e02b113c81c123",
  "node_id": "1905555364410802345",
  "variable_id": "1888794111663644672",
  "variable_value_enums": [
    "string"
  ]
}
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

Attribute

Name Type Required Description
robot_answer_type string yes Answer type
robot_answer_message_type string yes Message type
answer string false Answer
transfer_result string false Trans-to-agent result
roundid string yes Message round id
msgid string yes Message id
ai_agent_cid string yes AiAgent chat id
biz_id string yes Business id
robot_name string yes Bot name
robot_logo string yes Bot logo
robotid string yes Bot id
robot_status string yes Bot status
delay integer yes Node delay
output_variable_infos AnswerVariableInfo false Return collection variable
process_id string false Workflow id
node_id string false Node id
variable_id string false Variable id
variable_value_enums array false Enum list

Enum value

Attribute Value Description
robot_answer_type QA_DIRECT Direct answer
robot_answer_type DOCUMENT_DIRECT Document direct answer
robot_answer_type PROCESS Process start
robot_answer_type PROCESS_DOING Process ongoing
robot_answer_type PROCESS_DOING_UNKOW Task process is ongoing, hit unknown answer
robot_answer_type PROCESS_DOING_LLM Task process is ongoing, prompt generated by the large model
robot_answer_type PROCESS_DOING_QA_GENERAL Task process is ongoing, hit general knowledge
robot_answer_type PROCESS_DOING_CLEAR Task process is ongoing, process clarification
robot_answer_type PROCESS_DOING_SLOT_CLEAR Task process is ongoing, slot value clarification
robot_answer_type PROCESS_DOING_QA_DIRECT Task process is ongoing, hit QA direct answer
robot_answer_type PROCESS_DOING_DOCUMENT_DIRECT Task process is ongoing, hit document direct answer
robot_answer_type PROCESS_ERROR Task process_exception
robot_answer_type PROCESS_END Task process end
robot_answer_type PROCESS_VALUE_ERROR Variable enum value not obtained
robot_answer_type TRANSFER_INTENTION Trans-to-agent intent
robot_answer_type UNKNOWN Unknown answer
robot_answer_type GENERAL General knowledge answer
robot_answer_message_type MESSAGE Message parsing
robot_answer_message_type ANSWER_INFO Answer parsing
robot_answer_message_type ERROR Parsing error
robot_answer_message_type ERROR_END Chat has been terminated
robot_answer_message_type PROCESS_INFO Process parsing
transfer_result NO_ACTION Not trans-to-agent
transfer_result KEY_WORD Trans-to-agent by keywords
transfer_result GPT_TRANSFER Intent trans-to-agent
transfer_result REPEAT Repetitive question trans-to-agent
transfer_result NEGATIVE_EMOTIONS Trans-to-agent by neg. emotions
transfer_result MUCH_UNKNOWN Multiple unknowns trans-to-agent
transfer_result PROCESS_NODE_TRANSFER Process node trans-to-agent
robot_status DELETE Large-model bot has been deleted
robot_status ENABLE Large-model bot is functioning normally
robot_status EXPIRE Large-model bot has expired and is disabled
robot_status EXHAUST The Q&As of the large-model bot has been used up

Enum value

Attribute Value Description
bizType AI_AGENT Large-model bot

# Instructions for AI agent calling enterprise interfaces

Scope of use:

This document is used to specify the norms for AI agent invoking external enterprise interfaces, mainly involving the task workflow interface nodes and the action management module.

# 1.Supported Interface Types
  • Interface Configuration Method

 When configuring interfaces in the task workflow interface node and action management module, you need to configure the interface according to the screenshot path first. You can customize Header parameters, request parameters, and output parameters. img.png

  • Supported Interface Types

 Currently, the large model only supports POST requests, and the request header must include Content-Type as application/json.

  • Request Parameters

 When the AI agent calls the enterprise interface, partnerId, params, and multiParams will be used as fixed input parameters. It is recommended to use the application/json format for the request parameter type; otherwise, it may lead to interface call failure.

Field Name Field Description Type
partnerId At the start of the chat, you pass the customer's integration ID to Sobot. If not passed, it is empty. Fixed Parameters
params When the chat starts, the value it receives is a JSON-formatted string. Supported channels: web-JS, Android SDK, IOS SDK, WeChat Agent, WeChat Mini Program. Fixed Parameters
multiParams At the start of the chat, the multiParams parameter you pass should be in JSON key-value pair format, e.g., {"city":"Beijing","category":"Shirt"}. If not passed, it is empty. Supported channels: web-JS, Android SDK, iOS SDK. Fixed Parameters
source Chat channel. 0 for desktop website (PC), 2 for APP, 4 for mobile website (H5). Fixed Parameters
robotNo When the chat starts, the multiParams parameter you pass in should be in JSON key-value pair format, such as: {"city":"Beijing","category":"Shirt"}. If not passed, it is empty. Supported channels: web-JS, Android SDK, IOS SDK. Fixed Parameters
docId The issue ID for calling this interface Fixed Parameters
Custom Parameters Your custom request parameters. Fixed Parameters
  • Return Parameters

 The returned parameters can be used for subsequent conversations with the AI agent. If you need to use the "task workflow - interface node - message card" function, please use the Json format interface and fill in the JSONpath expression to extract the numerical value from the returned result of the interface. For specific configuration, please refer to the help documentation. Message Card Configuration | Help Center (opens new window)

# 2.Interface Call Authentication

 Each time the AI agent calls the enterprise interface, we will pass in two fixed custom parameters, params and mulitParams, with each call.

 If an enterprise needs to use a dynamic token for authentication, it can place the token field in the params and mulitParams fields for integration. Each time the AI agent calls the enterprise's interface, the params and mulitParams fields will be returned to the enterprise's interface. The enterprise interface can then authenticate based on its own requirements, which can be used to verify user identity and prevent unauthorized API calls.

  • Request Example
  curl https://xxxx.com/api/xxxx
  POST
  -H "Content-Type:application/json"
  -H "Header:value" //Custom header parameters
  -D "partnerId=xxx&multiParams={\"xx\":\"xx\"}&token=xxxx&source=0&robotNo=1&docId=xxxx. //You can append the token to the Params or multiParams field.
1
2
3
4
5
# 3.Enterprise Parameter Assignment Variable

 If you wish to assign a value to a specific variable through enterprise parameter passing, you can first create a variable in "AI Agent - Variable Management," then append the variable's code to the params or multiParams field. At this point, the numerical value passed by the enterprise will be directly assigned to the bot variable.

img.png

  • Example
  initInfo&multiParams = {"city":"Beijing","category":"Shirt"}
1

# AI Agent-Reception Records

# ● Reception Records List

Request method:POST

Request URL:

 https://sg.sobot.io/ai-agent-open/api/statistics/recordList
1

Request param:

Param Type Required Description
start_time String YES Start Time, format: yyyy-MM-dd
end_time String YES End Time, format: yyyy-MM-dd
page_no Integer YES Query page number
page_size Integer YES Query page size
robotid String NO Robot ID, separated by commas (see: Get Robot List Interface)
biz_type String NO Business Type, separated by commas (see: biz_type Enum)
source String NO Channel Type, separated by commas (see: source Enum)
channel_flag_plus String NO Consultation Channel, separated by commas (see: Get Consultation Channel Interface)
cid String NO Robot Session ID
bizid String NO Business Line Session ID
transfer2_human Integer NO Whether successful transfer to human 1-yes 0-no
trigger2_human Integer NO Whether triggered transfer to human 1-yes 0-no
timeZoneid String NO Time zone (default: Asia/Shanghai), (see: Get Time Zone Interface)
solve_status Integer NO Resolution status 1-confirmed solved 2-inferred solved 3-unsolved
answer_type String NO Answer Type, separated by commas (see: answer_type Enum)
valid_trigger2_human_type String NO Transfer to human Type, (see：valid_trigger2_human_type enum)
emotion_type String NO Expression of satisfaction POSITIVE--satisfied NEGATIVE--unsatisfied
satisfaction_status Integer NO Whether evaluated in session 1--evaluated 0--not evaluated
score_level String NO Score evaluation （see:score_level enum）
star_level String NO Star evaluation （see:star_level enum）
assess_status String NO Secondary evaluation 5--satisfied 1--unsatisfied
satisfaction_labels List NO Session evaluation labels （see: Get session label interface）
test Integer NO Whether test session 0:Non-test Chat 1:Test Chat
like_dislike_status Integer NO Like Dislike Status 1-Like 2-Dislike 3-Answer Not Evaluated
like_dislike_labels List NO Dislike Labels （see: Interface: Get Dislike Labels Interface）
robot_valid Integer NO Whether valid session 1-Valid Chat 0-Invalid Chat
robot_consult Integer NO Whether session ended 0-Chatting 1-Ended
rule_ids List NO Audience id collection （see: Get Audience interface）
is_trigger_session_guide_status Integer NO Whether triggered session guide 0-not triggered 1-triggered
robot_types List NO Robot Type AI_AGENT for large model robot, AI_COPILOT for large model co-pilot

Return param:

Param Type Description
ret_code String Return code
ret_msg String Return message
data Object data
total_count Integer Total pieces
page_no Integer Current page
page_size Integer Pieces on each page
page_count Integer Total pages

data object：

Param Type Description
robot_name String Bot Name
robot_valid Integer Whether valid session 1-valid session、0-invalid session
biz_type_enum String Business Type Enum
source String Channel Type
channel_flag String Channel Flag
user_msg_times Integer User Message Times
uid String uid
valid_trigger_other2_human Integer Other Method Trigger Transfer to Human
companyid String companyid
valid_trigger_ruler2_human Integer Rule Trigger Transfer to Human
like_dislike_status Integer Like/Dislike Status 1-Like 2-Dislike 3-Not Evaluated
satisfaction_status Integer Satisfaction Status 0-Not Evaluated 1-Evaluated
answer_variable_infos List Answer Variable Information
robot_consult Integer Session Status 0-In Session 1-Ended
test Integer Is Test Session 0-No 1-Yes
rule_infos List Audience Rule Information
channel_flag_plus String Extended Channel Flag
robot_flag String Robot Id
robot_type String Bot Type AI_AGENT/AI_COPILOT
valid_trigger2_human_type String Transfer to Human Type
transfer2_human Integer Successful Transfer to Human 0-No 1-Yes
biz_type String Business Type Name
trigger2_human Integer Trigger Transfer to Human 0-No 1-Yes
end_time Long End Timestamp
start_time Long Start Timestamp
channel_flag_name String Channel Name
answer_type List Answer Type
bizid String Business ID
robot_msg_times Integer Robot Message Times
cid String cid

Request example:

curl https://sg.sobot.io/ai-agent-open/api/statistics/recordList
-X POST 
-H 'token:cdc94901834c4190adbde1810d2d3a58' 
-H 'language:en' 
-H 'content-type: application/json' 
-d '
{
  "start_time": "2025-11-20",
  "end_time": "2025-11-20",
  "robot_types": [
    "AI_AGENT"
  ],
  "timeZoneid":"Asia/Shanghai",
  "robotid": "18,15,14",
  "biz_type": "TEXT,AI_AGENT",
  "source": "PC,wap,APP",
  "is_trigger_session_guide_status": 1,
  "trigger2_human": 0,
  "transfer2_human": 0,
  "rule_ids": [
    "a0546104b604441281419fc5b241417c"
  ],
  "page_no": 1,
  "page_size": 15,
  "answer_type": "2,3",
  "valid_trigger2_human_type": "REPEAT",
  "emotion_type": "POSITIVE",
  "assess_status": "5",
  "channel_flag_plus": "PC_24,PC_1",
  "robot_consult": 0,
  "solve_status": 2,
  "satisfaction_status": 1,
  "score_level": "10,9",
  "star_level": "5",
  "satisfaction_labels": [
    "3bde5e888b8c447fb437eafb3f750992"
  ],
  "robot_valid": 1,
  "test": 1,
  "like_dislike_status": 2,
  "like_dislike_labels": [
    "73da2cf57f42402b9c362fa1e4f62d6f"
  ],
  "cid": "f2f0daf6552c4078893932b50dfb963c"
}
'
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

Return example:

{
    "data": [
        {
            "robot_name": "test",
            "robot_valid": 0,
            "biz_type_enum": "TEXT",
            "source": "unknown",
            "channel_flag": "unknown",
            "user_msg_times": 1,
            "uid": "ad16e00bed9f4a21aedb6cc82e4c44e6",
            "valid_trigger_other2_human": 0,
            "companyid": "eb5c7fc458c54d6e978bab602673d504",
            "valid_trigger_ruler2_human": 0,
            "like_dislike_status": 3,
            "satisfaction_status": 0,
            "answer_variable_infos": [],
            "robot_consult": 1,
            "test": 0,
            "rule_infos": [
                {
                    "rule_name": "GV9P0w3v84",
                    "ruleid": "8196ed60ee6b4420a6e54d6fb40b2f1b"
                }
            ],
            "channel_flag_plus": "unknown_unknown",
            "robot_flag": "18",
            "robot_type": "AI_COPILOT",
            "valid_trigger2_human_type": "",
            "transfer2_human": 0,
            "biz_type": "Live Chat",
            "trigger2_human": 0,
            "end_time": 1763551895072,
            "start_time": 1763549376694,
            "channel_flag_name": "unknown",
            "answer_type": [],
            "bizid": "5bdcd797c7b14d8cbd29ad2e525f87ae",
            "robot_msg_times": 0,
            "cid": "f2f0daf6552c4078893932b50dfb963c"
        }
    ],
    "total_count": 32,
    "page_no": 1,
    "ret_msg": "success",
    "ret_code": "000000",
    "page_count": 3,
    "page_size": 15
}
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
# ● Robot List Interface

Request method:GET

Request URL:

 https://sg.sobot.io/ai-agent-open/api/statistics/queryAiRobotList
1

Request param:

Param Type Required Description
robotType String NO Bot Type 1 AI AGENT 2 AI Copilot

Request example:

curl https://sg.sobot.io/ai-agent-open/api/statistics/queryAiRobotList
-H 'token:cdc94901834c4190adbde1810d2d3a58' 
-H 'language:en'
1
2
3

Return example:

{
   "data": [
   	{
   		"kbid": 56,
   		"create_time": 1762165449497,
   		"robot_type": 1,
   		"robot_name": "cccc",
   		"robot_logo": "https://img-sg.sobot.com/static-resource/online-agent/image/newRbtPreviewFace.png",
   		"robot_model_status": "DRAFT",
   		"update_name": "test",
   		"updateid": "0a8c83731fd04728ac2ed13e9ef180dc",
   		"update_time": 1762165449497,
   		"companyid": "eb5c7fc458c54d6e978bab602673d504",
   		"robot_model": "NORMAL",
   		"configid": "a3e0b660f69e4f35b8d0438393672061",
   		"robot_veritable_remark": ""
   	}
   ],
   "ret_msg": "success",
   "ret_code": "000000"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# ● Consultation Channel Interface

Request method:POST

Request URL:

 https://sg.sobot.io/ai-agent-open/api/statistics/sourceList
1

Request param:

Param Type Required Description
start_time String YES Start Time
end_time String YES End Time
timeZoneid String NO Timezone（defaule: Asia/Shanghai）

Return param:

Param Type Description
kbid Integer Bot Id
robot_type Integer Bot Type
robot_name String Bot Name
robot_logo String Bot Logo
companyid String CompanyId
create_time long Create Time

Request example:

curl https://sg.sobot.io/ai-agent-open/api/statistics/sourceList
-X POST 
-H 'token:cdc94901834c4190adbde1810d2d3a58' 
-H 'language:en' 
-H 'content-type: application/json' 
-d '
{
  "start_time": "2025-11-20",
  "end_time": "2025-11-20",
  "timeZoneid":"Asia/Shanghai"
}
'
1
2
3
4
5
6
7
8
9
10
11
12

Return example:

{
   "data": [
   	{
   		"kbid": 56,
   		"create_time": 1762165449497,
   		"robot_type": 1,
   		"robot_name": "cccc",
   		"robot_logo": "https://img-sg.sobot.com/static-resource/online-agent/image/newRbtPreviewFace.png",
   		"robot_model_status": "DRAFT",
   		"update_name": "test",
   		"updateid": "0a8c83731fd04728ac2ed13e9ef180dc",
   		"update_time": 1762165449497,
   		"companyid": "eb5c7fc458c54d6e978bab602673d504",
   		"robot_model": "NORMAL",
   		"configid": "a3e0b660f69e4f35b8d0438393672061",
   		"robot_veritable_remark": ""
   	}
   ],
   "ret_msg": "success",
   "ret_code": "000000"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# ● Time Zone Interface

Request method:GET

Request URL:

 https://sg.sobot.io/ai-agent-open/api/statistics/getTimezoneInfo
1

Return param:

Param Type Description
timezoneid String Timezone Id
timezone_value String Timezone Value
create_time long Create Time

Request example:

curl https://sg.sobot.io/ai-agent-open/api/statistics/getTimezoneInfo
-H 'token:cdc94901834c4190adbde1810d2d3a58' 
-H 'language:en' 
-H 'content-type: application/json' 
'
1
2
3
4
5

Return example:

{
   "data": [
   	{
   		"create_time": 1676875112127,
   		"main_timezone_flag": 1,
   		"timezone": "+08:00",
   		"timezoneid": "Asia/Shanghai",
   		"id": "eb63c44816fc43bf9c55861670ebdad9",
   		"timezone_value": "GMT+08:00 beijing"
   	}
   ],
   "ret_msg": "success",
   "ret_code": "000000"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# ● Session label interface

Request method:GET

Request URL:

 https://sg.sobot.io/ai-agent-open/api/statistics/getLabels
1

Return param:

Param Type Description
name String Label Name
id String Label Id
create_time long Create Time

Request example:

curl https://sg.sobot.io/ai-agent-open/api/statistics/getLabels
-H 'token:cdc94901834c4190adbde1810d2d3a58' 
-H 'language:en' 
-H 'content-type: application/json' 
'
1
2
3
4
5

Return example:

{
	"data": [
		{
			"companyid": "eb5c7fc458c54d6e978bab602673d504",
			"raw_name": "{dc_welcom_message1}",
			"create_time": 1761547328,
			"name": "hello",
			"id": "f22b65ffc8a440af87dbe901e8f22313"
		}
	],
	"ret_msg": "success",
	"ret_code": "000000"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
# ● Dislike Labels Interface

Request method:GET

Request URL:

 https://sg.sobot.io/ai-agent-open/api/statistics/getLabelInfoList
1

Return param:

Param Type Description
name String Label Name
id String Label Id
create_time long Create Time

Request example:

curl https://sg.sobot.io/ai-agent-open/api/statistics/getLabelInfoList
-H 'token:cdc94901834c4190adbde1810d2d3a58' 
-H 'language:en' 
-H 'content-type: application/json' 
'
1
2
3
4
5

Return example:

{
	"data": [
		{
			"companyid": "eb5c7fc458c54d6e978bab602673d504",
			"create_time": 1758178949759,
			"createid": "dfdeb1b627c649e39b601a334200ddf6",
			"name": "123213",
			"is_del": 0,
			"id": "45d1568f195c47b6a98f011392c658af"
		}
	],
	"ret_msg": "success",
	"ret_code": "000000"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# ● Audience interface

Request method:GET

Request URL:

 https://sg.sobot.io/ai-agent-open/api/statistics/simpleList
1

Return param:

Param Type Description
rule_title String Audience Name
ruleid String Audience Id

Request example:

curl https://sg.sobot.io/ai-agent-open/api/statistics/simpleList
-H 'token:cdc94901834c4190adbde1810d2d3a58' 
-H 'language:en' 
-H 'content-type: application/json' 
'
1
2
3
4
5

Return example:

{
	"data": [
		{
			"rule_title": "test",
			"ruleid": "52e49616bfa2455abc3ccfbb10de1218"
		}
	],
	"ret_msg": "success",
	"ret_code": "000000"
}
1
2
3
4
5
6
7
8
9
10
# ● biz_type enum
Enum value Description
TEXT Live Chat
CALL Call Center
WORK_ORDER Ticket
AI_AGENT Open Platform
# ● source enum
Enum value Description
PC Desktop Site
wap Mobile Site
APP App
Email Email
wxkf WeChat Agent
miniApp WeChat Mini-Program
weChat WeChat Official Account
fb Facebook
whatsApp WhatsApp
instagram Instagram
line line
discord Discord
telegram Telegram
shopify shopify
twitter twitter
TikTok Shop TikTok
Amazon Amazon
Walmart Walmart
Zalo Zalo
Kakao Kakao
Lazada Lazada
rednote rednote
# ● answer_type enum
Enum value Description
1 Knowledge Answer - Direct Answer
2 Knowledge Answer - Questions / Articles / Files / Webpages
3 Knowledge Answer - Task Workflow
4 Intelligent Answer
# ● valid_trigger2_human_type enum
Enum value Description
KEY_WORD Keywords
REPEAT Continuously Repetitive Question
PROCESS_NODE_TRANSFER Task Workflow Trans-to-Agent
OTHER Trans-to-Agent Through Other Methods
CUSTOM_SCENE Custom Scenario Trans-to-Agent
MUCH_UNKNOWN Missing Knowledge
# ● score_level enum
Enum value Description
10 10 Scores (Pos. Feedback)
9 9 Scores (Pos. Feedback)
8 8 Scores (Neu. Feedback)
7 7 Scores (Neu. Feedback)
6 6 Scores (Neg. Feedback)
5 5 Scores (Neg. Feedback)
4 4 Scores (Neg. Feedback)
3 3 Scores (Neg. Feedback)
2 2 Scores (Neg. Feedback)
1 1 Scores (Neg. Feedback)
0 0 Scores (Neg. Feedback)
# ● star_level enum
Enum Value Description
5 5 Stars (Pos. Feedback)
4 4 Stars (Neu. Feedback)
3 3 Stars (Neu. Feedback)
2 2 Stars (Neg. Feedback)
1 2 Stars (Neg. Feedback)
Last Updated: 12/10/2025, 3:56:18 PM

← Live Chat Statistics API→

Update Date
01
CallCapability(Android-SDK)
12-25
02
Android SDK V7
10-22
03
iOS SDK V6
10-22
More Articles>
Theme by Vdoing