Live Chat Statistics API
# Live Chat Statistics API
# API Declaration
The "token" param must be contained in the header of the https request when calling the API.
Token is the only global API call credential for the Sobot API open platform. It is used when developers call the business APIs and thus should be properly kept. At least 32 chars should be reserved to store token. The validity period of token is currently 24 hours. It needs to be refreshed regularly or reacquired according to the token failure prompt returned by the API. When requesting the token API, regardless of the existence of token, a new token will be returned and its expiry time will be reset (currently 24 hours).
Token usage description:
- Developers need to obtain and manage the token uniformly. When calling the Sobot open APIs of various business, they should use the same token, instead of refreshing and obtaining new tokens for each business. Otherwise, it will easily lead to token invalidation and affect the normal API call.
- The current validity period of the token is transmitted by the returned expire_in, which is currently a value within 86,400 s. Developers need to refresh the new token in advance based on this valid time.
- Developers should reacquire the token according to the token invalidation prompt returned by the API.
# API Call
# ● Get the Access Token Code
API description:
Get the open API token, which is only applicable to all APIs of Sobot Open Platform v5.0. Contact the Sobot after-sales service personnel to get appid and app_key in the API.
Request method:
GET
Request URL:
https://sg.sobot.io/api/get_token
Request param:
Param | Type | Required | Description |
---|---|---|---|
appid | String | Yes | API credential ID |
create_time | String | Yes | Timestamp |
sign | String | Yes | Signature |
Return param:
Param | Type | Required | Description |
---|---|---|---|
ret_code | String | Yes | Return code |
ret_msg | String | Yes | Return message |
item | Object | No | Return object |
item object:
Param | Type | Required | Description |
---|---|---|---|
token | String | Yes | token code |
expires_in | String | Yes | Credential valid time |
Timestamp conversion tool:
https://www.unixtimestamp.com/
sign signature generation example:
E.g.: appid = "1"; create_time="1569397773"; app_key="2"
sign = Md5("115693977732") is 258eec3118705112b2c53dc8043d4d34.
Request example:
curl https://sg.sobot.io/api/get_token?appid=1&create_time=1569397773&sign=258eec3118705112b2c53dc8043d4d34
Return example:
{
"item": {
"token": "4ac37cb2e9c740dba4b75a34d5358802",
"expires_in": "86400"
},
"ret_code": "000000",
"ret_msg": "success"
}
2
3
4
5
6
7
8
# Param and Status Code Description
# PARAM
Request header param description:
Param | Type | Required | Description | Remarks |
---|---|---|---|---|
token | String | Yes | token | |
timezoneid | String | No | Time zone | standard time zone ID, not passed or defaulted to "Asia/Shanghai" illegally |
language | String | No | Language tag | en: English, zh: Chinese, not passed or defaulted to "zh" illegally |
Other param description:
For the input time description, if there are no special remarks on the regular API, the passed time is usually greater than the current time. To ensure the legitimacy of input, we will reset the input time to the current time based on the designated pattern of the API. For example, if today is September 11, 2023, assuming the passed time is September 12, 2023, the time will be reset to September 11, 2023.
If the passed time is the start time and end time, there is usually no special description for the API, and the end time cannot be greater than the start time.
Time format description:
pattern | Date |
---|---|
yyyy-MM-dd | 2023-09-01 |
yyyy-MM-dd HH:mm | 2023-09-01 00:00 |
yyyy-MM-dd HH:mm:ss | 2023-09-01 00:00:00 |
# Uniform Status Code Description
Return param:
Error Code | Description |
---|---|
000000 | Succeed |
900001 | Token is null! |
900002 | token authentication failed |
229000 | API call too frequent |
222000 | API input error |
999999 | System internal error |
Return example:
{
"ret_code": "000000",
"ret_msg": "Succeed",
"item": {}
}
2
3
4
5
{
"ret_code": "900001",
"ret_msg": "Token is null!"
}
2
3
4
{
"ret_code": "900002",
"ret_msg": "Token invalid or not found. Get a new one!"
}
2
3
4
{
"ret_code": "229000",
"ret_msg": "API call too frequent. Try again [60]s later. Currently [20] times of API call within [60]s is allowed. Excess will be limited!"
}
2
3
4
{
"ret_code": "222000",
"ret_msg": "[startTime] and [endTime] time range cannot be greater than [90]d. Current [startTime] input is [2023-01-01], and [endTime] input is [2023-09-01]"
}
2
3
4
{
"ret_code": "999999",
"ret_msg": "Unknown System Exception"
}
2
3
4
5
# Agent Statistics API
# ● Agent Workload Statistics (Paging)
Request method:
POST
Request URL:
https://sg.sobot.io/chat-static-api/api/customerService/staffWorkStatis
Request param:
Param | Type | Required | Description | Remarks |
---|---|---|---|---|
search_way | Integer | Yes | 1- Department 2- Group | It is empty. search_way=2 |
start_date | String | Yes | Operation Start Time | pattern:yyyy-MM-dd |
end_date | String | Yes | Operation End Time | pattern:yyyy-MM-dd |
staff_id_list | Array | No | Agent ID | ["staffId1","staffId2"] |
group_id_list | Array | No | Group ID | ["groupId1","groupId2"] |
page_no | String | No | Page | Default 1 |
page_size | String | No | Number on each page | Default 15,The maximum allowed is 100, and if it exceeds 100, it will be reset to 100. |
Return param:
Param | Type | Required | Description |
---|---|---|---|
ret_code | String | Yes | Return code |
ret_msg | String | Yes | Return message |
page_no | String | Yes | Current page |
page_count | String | Yes | Total pages |
page_size | String | Yes | Page Number |
total_count | String | Yes | Total Pieces of Data |
items | Array | No | Return object |
items object:
Param | Type | Required | Description |
---|---|---|---|
service_nick | String | No | Agent Nickname |
service_email | String | No | Agent Email |
group_name | String | No | Agent Skill Group |
human_consult | Integer | No | Total Chats |
human_self | Integer | No | Bot Reception Chats |
human_valid | Integer | No | Valid Chats |
human_invalid | Integer | No | Invalid Chats |
human_invalid_recep | Integer | No | Invalid Reception Chats |
first_response_time_set | Integer | No | 1st Reception-1st Response Chats |
transfer_first_res_duration | Long | No | Transferred 1st-Response Chats |
valid_recep_rate_str | String | No | Valid Reception Chat % |
not_recep_rate_str | String | No | Unreceived Chat % |
max_conv_num | String | No | Max received chats |
human_consult_duration_str | String | No | Agent Inquiry Duration |
valid_information | Integer | No | Valid Info-Collecting Chats |
human_valid_recep | Integer | No | Valid Reception Chats |
valid_response_counts | Long | No | Valid interactive chats |
avg_human_confirm_duration_transfer_str | String | No | Transfer Duration |
total_human_message | Integer | No | Total Chats |
msg_staff | Integer | No | Agent Messages |
msg_visitor_tostaff | Integer | No | No. of Message From Customer |
answer_than_str | String | No | A&Q % |
msg_staff_wordcount | Integer | No | Agent Chars |
human_visitor_consult | Long | No | Valid Inquiry Chats |
roll_in | Integer | No | Transfer-in Chats |
roll_out | Integer | No | Transfer-out Chats |
human_not_recep | Integer | No | Unreceived Chats |
last_staff_consult | Long | No | Last Reception Chats |
quiet_after_session_count | Long | No | 24h FCR |
quiet_after_session_rate_str | String | No | 24h FCR % |
human_initiative | Integer | No | Proactive Chats |
avg_session_duration_str | String | No | Avg. Agent Reception Time |
avg_total_session_duration_str | String | No | Avg. Total Chat Duration |
avg_first_response_time_str | String | No | Avg. 1st Response Time |
transfer_first_response_rate_str | String | No | Transferred 1st Response % |
response_time_avg_str | String | No | Avg. Response Time |
response_duration_max_str | String | No | Max Response Time |
first_response_rate_str | String | No | 1st Response % |
first_response_in30s_rate_str | String | No | 30s Response % |
first_response_in60s_rate_str | String | No | 60s Response % |
solve_not_mark | Integer | No | Chats not Tagged as Resolved or Unresolved |
snatch_out | Integer | No | Taken-Away Chats |
response_counts | Integer | No | Agent chat round level |
summary_solved | Integer | No | Resolved Chats |
summary_not_solved | Integer | No | Unresolved Chats |
snatch_in | Integer | No | Taken-Away Chats |
response_rate_str | String | No | Agent final response % |
staff_connect_rate_str | String | No | Agent Connection % |
human_res_warn_count | Integer | No | Agent chat response alert round level |
human_res_warn_rate_str | String | No | Agent chat response alert rate |
total_times | Integer | No | Chat Feedback |
comment_rate_str | String | No | Feedback % |
initiative | Integer | No | Proactive Customer Feedback |
customer_initiative_rate_str | String | No | Proactive Customer Feedback % |
invite_counts | Integer | No | Invitations |
invite_counts_rate_str | String | No | Invitation % |
invites | Integer | No | Agent-Invited Feedback |
staff_invite_rate_str | String | No | Agent-Invited Feedback % |
level2_score5_rate_str | String | No | Satisfication % (level 2 evaluation) |
level2_score1_rate_str | String | No | Dissatisfication % (level 2 evaluation) |
avg_comment_score | Double | No | Avg. Score (5 Stars) |
good_rate_str | String | No | Positive Feedback % (5 Stars) |
middle_rate_str | String | No | Moderate Feedback % (5 Stars) |
bad_rate_str | String | No | Neg. Feedback % (5 Stars) |
score5_rate_str | String | No | 5 Stars % |
score4_rate_str | String | No | 4 Stars % |
score3_rate_str | String | No | 3 Stars % |
score2_rate_str | String | No | 2 Stars % |
score1_rate_str | String | No | 1 Stars % |
avg_nps_score | Double | No | Avg. Score (10 Scores) |
good_nps_rate_str | String | No | Positive Feedback % (10 Scores) |
middle_nps_rate_str | String | No | Moderate Feedback % (10 Scores) |
bad_nps_rate_str | String | No | Neg. Feedback % (10 Scores) |
nps_score10_rate_str | String | No | 10 Scores % |
nps_score9_rate_str | String | No | 9 Scores % |
nps_score8_rate_str | String | No | 8 Scores % |
nps_score7_rate_str | String | No | 7 Scores % |
nps_score6_rate_str | String | No | 6 Scores % |
nps_score5_rate_str | String | No | 5 Scores % |
nps_score4_rate_str | String | No | 4 Scores % |
nps_score3_rate_str | String | No | 3 Scores % |
nps_score2_rate_str | String | No | 2 Scores % |
nps_score1_rate_str | String | No | 1 Scores % |
level2_score5 | Integer | No | Satisfication Chats (level 2 evaluation) |
level2_score1 | Integer | No | Dissatisfication Chats (level 2 evaluation) |
good | Integer | No | Chats with Positive Feedback (5 Stars) |
middle | Integer | No | Chats with Moderate Feedback (5 Stars) |
bad | Integer | No | Chats with Neg. Feedback (5 Stars) |
score5 | Integer | No | 5-Star Chats |
score4 | Integer | No | 4-Star Chats |
score3 | Integer | No | 3-Star Chats |
score2 | Integer | No | 2-Star Chats |
score1 | Integer | No | 1-Star Chats |
nps_good | Integer | No | Chats with Positive Feedback (10 Scores) |
nps_middle | Integer | No | Chats with Moderate Feedback (10 Scores) |
nps_bad | Integer | No | Chats with Neg. Feedback (10 Scores) |
nps_score10 | Integer | No | 10-Score Chats |
nps_score9 | Integer | No | 9-Score Chats |
nps_score8 | Integer | No | 8-Score Chats |
nps_score7 | Integer | No | 7-Score Chats |
nps_score6 | Integer | No | 6-Score Chats |
nps_score5 | Integer | No | 5-Score Chats |
nps_score4 | Integer | No | 4-Score Chats |
nps_score3 | Integer | No | 3-Score Chats |
nps_score2 | Integer | No | 2-Score Chats |
nps_score1 | Integer | No | 1-Score Chats |
remark | Integer | No | Remarks |
Request example:
curl--location'https://sg.sobot.io/chat-static-api/api/customerService/staffWorkStatis'\
--header 'token: c84f8b6f5885434da40d8449eb15c7f1' \
--header 'language: zh' \
--header 'timezoneid: Asia/Shanghai' \
--header 'Content-Type: application/json' \
--data '{
"search_way":"1",
"start_date": "2023-04-01",
"end_date": "2023-06-30",
"staff_id_list": ["staff_id1","staff_id2"],
"group_id_list": ["group_id1","group_id2"],
"page_no": "1",
"page_size": "15"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
Return example:
{
"ret_code": "000000",
"ret_msg": "Succeed",
"page_no": 1,
"page_count": 1,
"total_count": 5,
"page_size": 15,
"items": [
{
"start_date": "2025-03-19",
"end_date": "2025-04-17",
"group_id": "5a06cfe6bdac42419c56ec7e15dd64e9",
"group_name": "group1",
"staff_id": "0a8c83731fd04728ac2ed13e9ef180dc",
"service_email": "staff1@zhichi.com",
"service_nick": "staff1",
"human_consult": 7,
"human_self": 0,
"human_valid": 4,
"valid_information": 0,
"human_invalid": 3,
"human_valid_recep": 0,
"human_invalid_recep": 0,
"first_response_time_set": 0,
"transfer_first_res_duration": 0,
"human_visitor_consult": 4,
"valid_recep_rate_str": "0.00%",
"roll_in": 1,
"roll_out": 1,
"human_not_recep": 4,
"not_recep_rate_str": "100.00%",
"last_staff_consult": 6,
"quiet_after_session_count": 2,
"quiet_after_session_rate_str": "33.33%",
"human_initiative": 0,
"human_consult_duration": 2099106,
"human_consult_duration_str": "00:34:59",
"avg_session_duration": 301885.75,
"avg_session_duration_str": "00:05:01",
"avg_total_session_duration": 299872.2857,
"avg_total_session_duration_str": "00:04:59",
"summary_solved": 0,
"summary_not_solved": 0,
"solve_not_mark": 7,
"lastmsg_staff": 0,
"snatch_in": 0,
"snatch_out": 0,
"staff_connect_rate_str": "0.00%",
"avg_human_confirm_duration_transfer": 9073,
"avg_human_confirm_duration_transfer_str": "00:00:09",
"total_human_message": 9,
"msg_staff": 0,
"msg_visitor_tostaff": 9,
"answer_than_str": "0.00%",
"msg_staff_wordcount": 0,
"avg_first_response_time": 353669.5,
"avg_first_response_time_str": "00:05:53",
"first_response_rate_str": "0.00%",
"transfer_first_response_rate_str": "0.00%",
"response_time_avg": 353669.5,
"response_time_avg_str": "00:05:53",
"response_duration_max": 818770,
"response_duration_max_str": "00:13:38",
"first_response_in30s_rate_str": "0.00%",
"first_response_in60s_rate_str": "0.00%",
"total_times": 1,
"comment_rate_str": "25.00%",
"initiative": 0,
"customer_initiative_rate_str": "0.00%",
"invite_counts": 0,
"invite_counts_rate_str": "0.00%",
"invites": 1,
"staff_invite_rate_str": "100.00%",
"avg_comment_score": 0,
"good_rate_str": "0.00%",
"middle_rate_str": "0.00%",
"bad_rate_str": "0.00%",
"score5_rate_str": "0.00%",
"score4_rate_str": "0.00%",
"score3_rate_str": "0.00%",
"score2_rate_str": "0.00%",
"score1_rate_str": "0.00%",
"avg_nps_score": 10,
"good_nps_rate_str": "100.00%",
"middle_nps_rate_str": "0.00%",
"bad_nps_rate_str": "0.00%",
"nps_score10_rate_str": "100.00%",
"nps_score9_rate_str": "0.00%",
"nps_score8_rate_str": "0.00%",
"nps_score7_rate_str": "0.00%",
"nps_score6_rate_str": "0.00%",
"nps_score5_rate_str": "0.00%",
"nps_score4_rate_str": "0.00%",
"nps_score3_rate_str": "0.00%",
"nps_score2_rate_str": "0.00%",
"nps_score1_rate_str": "0.00%",
"nps_score0_rate_str": "0.00%",
"good": 0,
"middle": 0,
"bad": 0,
"score5": 0,
"score4": 0,
"score3": 0,
"score2": 0,
"score1": 0,
"nps_good": 1,
"nps_middle": 0,
"nps_bad": 0,
"nps_score10": 1,
"nps_score9": 0,
"nps_score8": 0,
"nps_score7": 0,
"nps_score6": 0,
"nps_score5": 0,
"nps_score4": 0,
"nps_score3": 0,
"nps_score2": 0,
"nps_score1": 0,
"nps_score0": 0,
"level2_score1": 0,
"level2_score5": 0,
"level2_score1_rate_str": "0.00%",
"level2_score5_rate_str": "0.00%",
"remark": 0,
"valid_response_counts": 0,
"response_rate_str": "0.00%",
"max_conv_num": "1",
"human_res_warn_count": 3,
"response_counts": 4,
"human_res_warn_rate_str": "75.00%"
},
{
"start_date": "2025-03-19",
"end_date": "2025-04-17",
"group_id": "5a06cfe6bdac42419c56ec7e15dd64e9",
"group_name": "group2",
"staff_id": "903965b75366482dbc95a4322538e2c8",
"service_email": "staff2@zhichi.com",
"service_nick": "staff2",
"human_consult": 9,
"human_self": 1,
"human_valid": 6,
"valid_information": 0,
"human_invalid": 3,
"human_valid_recep": 1,
"human_invalid_recep": 0,
"first_response_time_set": 0,
"transfer_first_res_duration": 0,
"human_visitor_consult": 6,
"valid_recep_rate_str": "16.67%",
"roll_in": 0,
"roll_out": 0,
"human_not_recep": 5,
"not_recep_rate_str": "83.33%",
"last_staff_consult": 9,
"quiet_after_session_count": 2,
"quiet_after_session_rate_str": "22.22%",
"human_initiative": 0,
"human_consult_duration": 4363974,
"human_consult_duration_str": "01:12:43",
"avg_session_duration": 228155.6667,
"avg_session_duration_str": "00:03:48",
"avg_total_session_duration": 484886,
"avg_total_session_duration_str": "00:08:04",
"summary_solved": 0,
"summary_not_solved": 0,
"solve_not_mark": 9,
"lastmsg_staff": 1,
"snatch_in": 0,
"snatch_out": 0,
"staff_connect_rate_str": "16.67%",
"avg_human_confirm_duration_transfer": 0,
"avg_human_confirm_duration_transfer_str": "00:00:00",
"total_human_message": 14,
"msg_staff": 7,
"msg_visitor_tostaff": 7,
"answer_than_str": "100.00%",
"msg_staff_wordcount": 50,
"avg_first_response_time": 392346,
"avg_first_response_time_str": "00:06:32",
"first_response_rate_str": "0.00%",
"transfer_first_response_rate_str": "0.00%",
"response_time_avg": 392346,
"response_time_avg_str": "00:06:32",
"response_duration_max": 572595,
"response_duration_max_str": "00:09:32",
"first_response_in30s_rate_str": "0.00%",
"first_response_in60s_rate_str": "0.00%",
"total_times": 0,
"comment_rate_str": "0.00%",
"initiative": 0,
"customer_initiative_rate_str": "0.00%",
"invite_counts": 0,
"invite_counts_rate_str": "0.00%",
"invites": 0,
"staff_invite_rate_str": "0.00%",
"avg_comment_score": 0,
"good_rate_str": "0.00%",
"middle_rate_str": "0.00%",
"bad_rate_str": "0.00%",
"score5_rate_str": "0.00%",
"score4_rate_str": "0.00%",
"score3_rate_str": "0.00%",
"score2_rate_str": "0.00%",
"score1_rate_str": "0.00%",
"avg_nps_score": 0,
"good_nps_rate_str": "0.00%",
"middle_nps_rate_str": "0.00%",
"bad_nps_rate_str": "0.00%",
"nps_score10_rate_str": "0.00%",
"nps_score9_rate_str": "0.00%",
"nps_score8_rate_str": "0.00%",
"nps_score7_rate_str": "0.00%",
"nps_score6_rate_str": "0.00%",
"nps_score5_rate_str": "0.00%",
"nps_score4_rate_str": "0.00%",
"nps_score3_rate_str": "0.00%",
"nps_score2_rate_str": "0.00%",
"nps_score1_rate_str": "0.00%",
"nps_score0_rate_str": "0.00%",
"good": 0,
"middle": 0,
"bad": 0,
"score5": 0,
"score4": 0,
"score3": 0,
"score2": 0,
"score1": 0,
"nps_good": 0,
"nps_middle": 0,
"nps_bad": 0,
"nps_score10": 0,
"nps_score9": 0,
"nps_score8": 0,
"nps_score7": 0,
"nps_score6": 0,
"nps_score5": 0,
"nps_score4": 0,
"nps_score3": 0,
"nps_score2": 0,
"nps_score1": 0,
"nps_score0": 0,
"level2_score1": 0,
"level2_score5": 0,
"level2_score1_rate_str": "0.00%",
"level2_score5_rate_str": "0.00%",
"remark": 0,
"valid_response_counts": 0,
"response_rate_str": "16.67%",
"max_conv_num": "1",
"human_res_warn_count": 2,
"response_counts": 6,
"human_res_warn_rate_str": "33.33%"
}
]
}
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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
Description:
- Currently, there is rate limiting for the API. When ret_code=229000, it indicates that the API has been rate-limited, with a current maximum allowance of 20 calls per minute.