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

AI Agent API

# Large-model bot

# 1. Q&A - Streaming

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

Body request param

{
  "question": "string",
  "show_question": "string",
  "input_type_enum": "INPUT",
  "biz_id": "string",
  "biz_type": "TEXT",
  "biz_type_id": "string",
  "robotid": "string",
  "uid": "string",
  "user_name": "string",
  "transfer": true,
  "ai_agent_cid": "string",
  "call_back_url": "string",
  "source_enum": "PC",
  "partnerid": "string",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": "false",
  "input_variable_infos": [
    {
      "variable_id": "string",
      "variable_name": "string",
      "variable_value": "string",
      "variable_type": "CHARACTER"
    }
  ],
  "process_info": {
    "process_id": "string",
    "node_id": "string",
    "variable_id": "string",
    "variable_value": "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
31
32
33
34
35
36
37

# Request param

Name Location Type Required Description
body body RobotAnswerReqVo Yes

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

# 2. GET Q&A - Visitor side initialization

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

# Request param

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

Return example

Succeeded

{
  "data": {
    "bizid": "",
    "ai_agent_cid": "",
    "biz_type": "",
    "biz_typeid": ""
  },
  "retCode": "",
  "retMsg": ""
}
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 data structure

Type Required Constraint Description
InitRespVo yes none none

# 3. POST Q&A - Non-streaming

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

Body request param

{
  "question": "string",
  "show_question": "string",
  "input_type_enum": "INPUT",
  "biz_id": "string",
  "biz_type": "TEXT",
  "biz_type_id": "string",
  "robotid": "string",
  "uid": "string",
  "user_name": "string",
  "transfer": true,
  "ai_agent_cid": "string",
  "call_back_url": "string",
  "source_enum": "PC",
  "partnerid": "string",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": "false",
  "input_variable_infos": [
    {
      "variable_id": "string",
      "variable_name": "string",
      "variable_value": "string",
      "variable_type": "CHARACTER"
    }
  ],
  "process_info": {
    "process_id": "string",
    "node_id": "string",
    "variable_id": "string",
    "variable_value": "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
31
32
33
34
35
36
37

# Request param

Name Location Type Required Description
body body OpenRobotAnswerReqVo Yes none

Return example

Succeeded

{
  "data": [
    {
      "robot_answer_type": "",
      "robot_answer_message_type": "",
      "answer": "",
      "transfer_result": "",
      "roundid": "",
      "msgid": "",
      "ai_agent_cid": "",
      "biz_id": "",
      "robot_name": "",
      "robot_logo": "",
      "robotid": "",
      "robot_status": "",
      "delay": 0,
      "output_variable_infos": [
        {
          "variable_id": "",
          "variable_name": "",
          "variable_value": "",
          "variable_type": ""
        }
      ],
      "process_id": "",
      "node_id": "",
      "variable_id": "",
      "variable_value_enums": [
        ""
      ]
    }
  ],
  "retCode": "",
  "retMsg": ""
}
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

# 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

# 4. POST Q&A - Word association

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

Body request param

{
  "question": "string",
  "show_question": "string",
  "input_type_enum": "INPUT",
  "biz_id": "string",
  "biz_type": "TEXT",
  "biz_type_id": "string",
  "robotid": "string",
  "uid": "string",
  "user_name": "string",
  "transfer": true,
  "ai_agent_cid": "string",
  "call_back_url": "string",
  "source_enum": "PC",
  "partnerid": "string",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": "false",
  "input_variable_infos": [
    {
      "variable_id": "string",
      "variable_name": "string",
      "variable_value": "string",
      "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

# Request param

Name Location Type Required Description
body body RobotAnswerReqVo Yes none

Return example

Succeeded

{
  "data": {
    "qa_contents": [
      {
        "question": "",
        "questionid": "",
        "docid": "",
        "score": 0
      }
    ]
  },
  "retCode": "",
  "retMsg": ""
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 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

# 5. POST Q&A - Asynchronous

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

Body request param

{
  "question": "string",
  "show_question": "string",
  "input_type_enum": "INPUT",
  "biz_id": "string",
  "biz_type": "TEXT",
  "biz_type_id": "string",
  "robotid": "string",
  "uid": "string",
  "user_name": "string",
  "transfer": true,
  "ai_agent_cid": "string",
  "call_back_url": "string",
  "source_enum": "PC",
  "partnerid": "string",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": "false",
  "input_variable_infos": [
    {
      "variable_id": "string",
      "variable_name": "string",
      "variable_value": "string",
      "variable_type": "CHARACTER"
    }
  ],
  "process_info": {
    "process_id": "string",
    "node_id": "string",
    "variable_id": "string",
    "variable_value": "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
31
32
33
34
35
36
37

# Request param

Name Location Type Required Description
body body RobotAnswerReqVo Yes none

Return example

Succeeded

{
  "data": {},
  "retCode": "",
  "retMsg": "",
  "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

# 6. GET chat end

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

# Request param

Name Location Type Required Description
ai_agent_cid query string Yes none

Return example

Succeeded

{
  "data": {},
  "ret_code": "",
  "ret_msg": ""
}
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

# 7. GET polling timeout message

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

# Request param

Name Location Type Required Description
msgid query string Yes none

Return example

Succeeded

{
  "data": {
    "msgid": "",
    "data": {
      "msgid": "",
      "bizid": "",
      "ai_agent_cid": "",
      "round_id": "",
      "msg": "",
      "source_enum": "",
      "uid": "",
      "polling_id": "",
      "polling_status": ""
    },
    "bizid": "",
    "push_type": ""
  },
  "retCode": "",
  "retMsg": ""
}
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

# 8. 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

# 9. 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

# Data model

# PushInfo

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

# Attribute

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

# PushData format

{
      "msgid": "",
      "bizid": "",
      "ai_agent_cid": "",
      "round_id": "",
      "msg": "",
      "source_enum": "",
      "uid": "",
      "polling_id": "",
      "polling_status": ""
}
1
2
3
4
5
6
7
8
9
10
11

# Attribute

Name Type Required Constraint Description
msgid string yes none Message id
bizid string yes none Business id
ai_agent_cid string yes none Large-model bot chat id
round_id string yes none Round id
msg string false none Message
source_enum string yes none Source
uid string false none Visitor id
polling_id string yes none Polling id
polling_status string yes none 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": "string",
  "show_question": "string",
  "input_type_enum": "INPUT",
  "biz_id": "string",
  "biz_type": "TEXT",
  "biz_type_id": "string",
  "robotid": "string",
  "uid": "string",
  "user_name": "string",
  "transfer": true,
  "ai_agent_cid": "string",
  "call_back_url": "string",
  "source_enum": "PC",
  "partnerid": "string",
  "params": {
    "key": {}
  },
  "multi_params": {
    "key": {}
  },
  "timing": "false",
  "input_variable_infos": [
    {
      "variable_id": "string",
      "variable_name": "string",
      "variable_value": "string",
      "variable_type": "CHARACTER"
    }
  ],
  "process_info": {
    "process_id": "string",
    "node_id": "string",
    "variable_id": "string",
    "variable_value": "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
31
32
33
34
35
36
37
38

# Attribute

Name Type Required Constraint Description
question string yes none Question
show_question string yes none Display question
input_type_enum string yes none Input type
biz_id string yes none Business id
biz_type string yes none Business line type
biz_type_id string yes none Product id
robotid string yes none Bot id
uid string false none Visitor id
user_name string false none Visitor name
transfer boolean false none Whether to enable trans-to-agent
ai_agent_cid string false none AiAgent chat id
call_back_url string false none Callback URL
source_enum string yes none Channel source
partnerid string false none Docking id
params Map<String,Object> false none Custom param
multi_params Map<String,Object> false none Custom param
timing boolean false none Whether to enable external timing
input_variable_infos OpenAnswerVariableInfo false none Externally passed variable
process_info OpenProcessInfo false none 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
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": "string",
  "variable_name": "string",
  "variable_value": "string",
  "variable_code": "string",
  "variable_type": "CHARACTER"
}
1
2
3
4
5
6
7
8

# Attribute

Name Type Required Constraint Description
variable_id string yes none Variable id
variable_name string yes none Variable name
variable_value string yes none Variable value
variable_code string yes none Variable code
variable_type string yes none 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": "string",
  "node_id": "string",
  "variable_id": "string",
  "variable_value": "string"
}
1
2
3
4
5
6
7

# Attribute

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

# QaInfo

{
  "question": "string",
  "questionid": "string",
  "docid": "string",
  "score": 0
}
1
2
3
4
5
6
7

# Attribute

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

# RobotAnswerSuggestRespVo

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

# Attribute

Name Type Required Constraint Description
qaContents QaInfo yes none Word association list

# RobotAnswerRespVo

{
  "robot_answer_type": "QA_DIRECT",
  "robot_answer_message_type": "MESSAGE",
  "answer": "string",
  "transfer_result": "NO_ACTION",
  "roundid": "string",
  "msgid": "string",
  "ai_agent_cid": "string",
  "biz_id": "string",
  "robot_name": "string",
  "robot_logo": "string",
  "robotid": "string",
  "robot_status": "DELETE",
  "delay": 0,
  "output_variable_infos": [
    {
      "variable_id": "string",
      "variable_name": "string",
      "variable_value": "string",
      "variable_code": "string",
      "variable_type": "CHARACTER"
    }
  ],
  "process_id": "string",
  "node_id": "string",
  "variable_id": "string",
  "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 Constraint Description
robot_answer_type string yes none Answer type
robot_answer_message_type string yes none Message type
answer string false none Answer
transfer_result string false none Trans-to-agent result
roundid string yes none Message round id
msgid string yes none Message id
ai_agent_cid string yes none AiAgent chat id
biz_id string yes none Business id
robot_name string yes none Bot name
robot_logo string yes none Bot logo
robotid string yes none Bot id
robot_status string yes none Bot status
delay integer yes none Node delay
output_variable_infos AnswerVariableInfo false none Return collection variable
process_id string false none Workflow id
node_id string false none Node id
variable_id string false none Variable id
variable_value_enums array false none 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

# InitRespVo

{
  "bizId": "string",
  "aiAgentCid": "string",
  "bizType": "TEXT",
  "bizTypeId": "string"
}
1
2
3
4
5
6
7

# Attribute

Name Type Required Constraint Description
bizId string¦null false none Business id
aiAgentCid string¦null false none Current chat id
bizType string¦null false none Business line type
bizTypeId string¦null false none Product id

# Enum value

Attribute Value Description
bizType AI_AGENT Large-model bot
Last Updated: 2/7/2025, 10:24:15 AM

←

Update Date
01
Operations Support API
04-03
02
CRM Docking Scheme
12-05
03
LINE API
06-25
More Articles>
Theme by Vdoing