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

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

  • Message Push
  • Online Message Forwarding API
  • Knowledge Base V6 API
  • Chatbot Statistics API
  • Enterprise actively sends offline message API
  • Rule Engine API
  • AI Agent API
  • Live Chat Statistics API
    • Text Product API
    Sobot
    2025-04-23
    Menus

    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:

    1. Developers need to obtain and manage the token uniformly. When calling the Sobot open APIs of various business, they should use the same token, instead of refreshing and obtaining new tokens for each business. Otherwise, it will easily lead to token invalidation and affect the normal API call.
    2. The current validity period of the token is transmitted by the returned expire_in, which is currently a value within 86,400 s. Developers need to refresh the new token in advance based on this valid time.
    3. Developers should reacquire the token according to the token invalidation prompt returned by the API.

    # API Call

    # ● Get the Access Token Code

    API description:

    Get the open API token, which is only applicable to all APIs of Sobot Open Platform v5.0. Contact the Sobot after-sales service personnel to get appid and app_key in the API.

    Request method:

    GET

    Request URL:

     https://sg.sobot.io/api/get_token
    
    1

    Request param:

    Param Type Required Description
    appid String Yes API credential ID
    create_time String Yes Timestamp
    sign String Yes Signature

    Return param:

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

    item object:

    Param Type Required Description
    token String Yes token code
    expires_in String Yes Credential valid time

    Timestamp conversion tool:

    https://www.unixtimestamp.com/
    
    1

    sign signature generation example:

    E.g.: appid = "1"; create_time="1569397773"; app_key="2"

    sign = Md5("115693977732") is 258eec3118705112b2c53dc8043d4d34.

    Request example:

    curl https://sg.sobot.io/api/get_token?appid=1&create_time=1569397773&sign=258eec3118705112b2c53dc8043d4d34
    
    1

    Return example:

    {
      "item": {
        "token": "4ac37cb2e9c740dba4b75a34d5358802",
        "expires_in": "86400"
      },
      "ret_code": "000000",
      "ret_msg": "success"
    }
    
    1
    2
    3
    4
    5
    6
    7
    8

    # 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": {}
    }
    
    1
    2
    3
    4
    5
    {
      "ret_code": "900001",
      "ret_msg": "Token is null!"
    }
    
    1
    2
    3
    4
    {
      "ret_code": "900002",
      "ret_msg": "Token invalid or not found. Get a new one!"
    }
    
    1
    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!"
    }
    
    1
    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]"
    }
    
    1
    2
    3
    4
    
    {
      "ret_code": "999999",
      "ret_msg": "Unknown System Exception"
    }
    
    1
    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
    
    1

    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"
    }'
    
    1
    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%"
        }
      ]
    }
    
    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
    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:

    1. 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.
    Last Updated: 6/24/2025, 4:43:23 PM

    ← AI Agent API

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