Udesk-Customer service solution leader

Udesk API General Description

Fetch IM Conversation Records List

This interface is used to fetch multiple IM conversation records at once. Rate limit: 1 time/2 seconds

Request Method

GET /im/sessions/search

Request Parameters (Query String)

Parameter Name	Required	Description
start_time	No	Record start time: If no hour, minute, and second are passed, they default to 00:00:00. If not passed, it defaults to 00:00:00 of the query day.
end_time	No	Record end time: If no hour, minute, and second are passed, they default to 00:00:00. If not passed, it defaults to 24:00:00 of the query day.
status	No	Session status (close)
page	No	Page number, starting from 1, default is 1
page_size	No	Number of items per page, default is 30, maximum is 1000

Note:

The maximum time period from start_time to end_time is 30 days;

start_time and end_time default to the start time of the conversation when not specified, and when status=close, they are queried based on the end time of the conversation;

The format of start_time and end_time is "YYYY-MM-DD hh:mm:ss", or "YYYY-MM-DD" without time.

Response Data

Attribute Name	Type	Description
status	Integer	Execution result code, 0 represents success
message	String	Execution result explanation
size	Integer	Number of items returned in this request
total	Integer	Total number of data
total_pages	Integer	Total number of pages
item	Array	List of conversation records, see IM Data for details of each element

Example

curl https://demo.udesk.cn/open_api_v1/im/sessions/search?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Response

{
  "status": 0,
  "message": "success",
  "item": [
    {
      "session_id": 1,
      "sub_session_id": 1,
      "note_id": null,
      "customer_id": 1,
      "customer_name": "Test User",
      "customer_custom_fields": {},
      "agent_id": 1,
      "agent_nick_name": "Test Agent",
      "created_at": "2015-01-01 12:00:00",
      "closed_at": "2015-01-01 12:30:00",
      "resp_seconds": 7,
      "queue_seconds": "Not In Queue",
      "sustain_seconds": 128,
      "survey_vote_id": 1357334,
      "belong_queue": "queue_company_6_group_331",
      "agent_msg_num": 0,
      "customer_msg_num": 0,
      "source": "reocar.udesk.com",
      "source_url": "https://demo.udeskt.cn/im_client/",
      "queue_start_time": "2015-01-01 11:14:49",
      "conversations_num_today": 4,
      "platform": "web",
      "organization_id": null,
      "last_response": "customer",
      "alert_num": 1,
      "alert_desc": "Sensitive word once, response timeout, session timeout",
      "ticket_num": 2,
      "ticket_nos": "#140,#141",
      "im_web_plugin_id": 1,
      "sender": "customer",
      "active_guest": "agent",
      "menu_names": "Navigation menu",
      "transfer_to_agent": "Whether the robot transfers to a human",
      "robot_id": "robot id",
      "robot_name": "robot name",
      "close_method": "sys_close",
      "robot_session_id": 1,
      "resolved_state": "0",
      "web_info": {
        "login_url": null,
        "session_url": "https://demo.udesk.cn/im_client/",
        "keyword": null,
        "src": "demo.udesk.cn",
        "src_url": "https://demo.udesk.cn/im_client/",
        "sys": "Win7",
        "bowser": "Chrome56",
        "generated_channel": null,
        "ip": "123.123.123.123"
      },
      "ticket_ids": []
    }
  ],
  "size": 1,
  "total": 1,
  "total_pages": 1
}

Fetch IM Conversation Details

This interface is used to obtain detailed information about an IM conversation.

Request Method

GET /im/sessions/im_sub_session

Request Parameters (Query String)

Parameter Name	Required	Description
im_sub_session_id	Yes	ID of a single conversation

Response Data

Attribute Name	Type	Description
status	Integer	Execution result code, 0 represents success
message	String	Execution result explanation
im_sub_session_log	Array	Details of the conversation record, see IM Data for details of each element
im_log_infos	Array	Chat logs, see im_log_infos parameter description

Example

curl http://demo.udesk.cn/open_api_v1/im/sessions/im_sub_session?im_sub_session_id=1234567&email=admin@udesk.cn&sign_version=v2&nonce=1646221853&timestamp=1646221853&sign=ca821bef91abcd6057ff04024282edbae0856281

Response

{
    "status": 0,
    "message": "success",
    "im_sub_session_log": [
        {
            "session_id": 1234567,
            "sub_session_id": 123456,
            "note_id": null,
            "customer_id": 123456,
            "customer_name": "xxx",
            "customer_custom_fields": {
                "SelectField_32412442": [
                    "123"
                ]
            },
            "agent_id": 123,
            "agent_nick_name": "xx",
            "created_at": "2022-03-02 15:12:31",
            "closed_at": "2022-03-02 15:13:20",
            "resp_seconds": 28,
            "queue_seconds": "Not In Queue",
            "sustain_seconds": 49,
            "survey_vote_id": 123,
            "resolved_state_title": "Is the problem solved？1111111",
            "resolved_state_name": "Resolved",
            "resolved_state_value": "0",
            "platform": "web",
            "belong_queue": "queue_company_28480_agent_148002",
            "agent_msg_num": 3,
            "customer_msg_num": 2,
            "source": "demo.udesk.cn",
            "source_url": "https://demo.udesk.cn/im_client/?web_plugin_id=21&agent_id=12",
            "queue_start_time": "2022-03-02 15:12:31",
            "conversations_num_today": 1,
            "agent_invite_vote_count": null,
            "search_keyword": null,
            "custom_channel": null,
            "organization_id": null,
            "last_response": "agent",
            "alert_num": 1,
            "alert_desc": "Sensitive word",
            "ticket_num": 0,
            "ticket_nos": null,
            "im_web_plugin_id": 100042,
            "sender": "customer",
            "active_guest": "blank",
            "menu_names": null,
            "transfer_to_agent": false,
            "robot_id": null,
            "robot_name": null,
            "close_method": "agent_close",
            "robot_session_id": null,
            "resolved_state": "0",
            "web_info": {
                "login_url": null,
                "session_url": "https://demo.udesk.cn/im_client/?web_plugin_id=21&agent_id=12",
                "keyword": null,
                "src": "udesk-rd-bj-01.udesk.cn",
                "src_url": "https://demo.udesk.cn/im_client/?web_plugin_id=21&agent_id=12",
                "sys": "Win7",
                "bowser": "Chrome75",
                "generated_channel": null,
                "ip": "123.123.123.123"
            }
        }
    ],
    "im_log_infos": [
        {
            "id": 4359638049,
            "created_at": "2022-03-02 15:12:31",
            "sender": "customer",
            "user_id": 2618228342,
            "content": "{\"type\":\"message\",\"data\":{\"content\":\"There is new consultation coming in。\"},\"im_sub_session_id\":632362082,\"is_welcome\":true}",
            "session_id": 1234567,
            "sub_session_id": 123456,
            "survey_option_id": 1
        },
        {
            "id": 4359638058,
            "created_at": "2022-03-02 15:12:32",
            "sender": "agent",
            "user_id": 148002,
            "content": "{\"type\":\"rich\",\"data\":{\"content\":\"<p><img src=\\\"https://pro-cs-freq.oss-cn-hangzhou.aliyuncs.com/config/imtid28480/1111_1639730293210_js9ng.jpg\\\" /><br />This is the global welcome message, I will ask the group about rich text.</p>\"},\"push_type\":\"sys_welcome_msg\"}",
            "session_id": 1234567,
            "sub_session_id": 123456,
            "survey_option_id": 1
        }
    ]
}

Fetch Chat Logs for a Specific Customer

This interface is used to fetch chat logs for a specific user in one go. Rate limit: 50 times/60 seconds

Request Method

GET /im/sessions/customer_im_logs

Request Parameters (Query String)

Parameter Name	Type	Required	Description	Limitation
type	String	Yes	Type of condition for querying customers	No more than 255 characters
content	String	Yes	Content of the condition for querying customers	No more than 255 characters
start_time	Datetime	No	Record start time: If no hour, minute, and second are passed, they default to 00:00:00.
end_time	Datetime	No	Record end time: If no hour, minute, and second are passed, they default to 00:00:00.
page	Integer	No	Page number, starting from 1, default is 1

Condition types and content descriptions

Value	Corresponding meaning of content
id	Customer ID
email	Customer email
cellphone	Customer phone number
token	Customer external unique identifier, corresponding value open_api_token
weixin_open_id	Customer WeChat openid
weibo_id	Customer Weibo openid

Note:

The maximum time period from start_time to end_time is 90 days;

start_time and end_time query the creation time of im_sub_session;

The format of start_time and end_time is "YYYY-MM-DD hh:mm:ss", or "YYYY-MM-DD" without time.

Response Data

Attribute Name	Type	Description
status	Integer	Execution result code, 0 represents success
message	String	Execution result explanation
size	Integer	Number of items returned in this request
total	Integer	Total number of data
total_pages	Integer	Total number of pages
item	Array	Chat log list, details of each element as follows

Item content

Attribute Name	Type	Description
im_sub_session_id	Integer	im_sub_session's id
im_log_infos	Array	Chat logs under im_sub_session, see below

im_log_infos content

Attribute Name	Type	Description
id	Integer	im_log's id
created_at	Datetime	im_log's creation time
sender	String	Message sender
user_id	Integer	Message sender's id
nick_name	String	Sender's nickname
content	Array	Chat content, see below for details of the content's type

Example

curl https://demo.udesk.cn/open_api_v1/im/sessions/customer_im_logs?email=admin@udesk.cn&sign_version=v2&nonce=1646278574&sign=b361abcdb6a8a2a42cc137498515cb4054bf32f2&timestamp=1646278574&start_time=2022-03-03 00:00:00&end_time=2022-03-03 23:59:59&page=1&type=id&content=43038556

Response Data

{
    "status": 0,
    "message": "Success",
    "item": [
        {
            "im_sub_session_id": 123,
            "im_log_infos": [
                {
                    "id": 1234,
                    "created_at": "2022-03-03 11:32:59",
                    "sender": "customer",
                    "user_id": 123456,
                    "nick_name": "Jack",
                    "content": "{\"type\":\"message\",\"platform\":\"wechat\",\"data\":{\"content\":\"Hello!\",\"duration\":null,\"translation\":null}}"
                }
            ]
        }
    ],
    "size": 1,
    "total": 1,
    "total_pages": 1
}

Fetch Chat Logs List

This interface is used to obtain chat logs information for a specified IM session. Rate limit: 1 time/2 seconds

Request Method

GET /im/sessions/log

Request Parameters (Query String)

Parameter Name	Required	Description
session_id	Yes	IM session ID
start_time	No	Record start time: If no hour, minute, and second are passed, they default to 00:00:00. If not passed, it defaults to 00:00:00 of the query day.
end_time	No	Record end time: If no hour, minute, and second are passed, they default to 00:00:00. If not passed, it defaults to 24:00:00 of the query day.
page	No	Page number, starting from 1, default is 1
page_size	No	Number of items per page, default is 30, maximum is 1000

start_time and end_time query the creation time of the chat logs; The format of start_time and end_time is "YYYY-MM-DD hh:mm:ss", or "YYYY-MM-DD" without time.

Response Data

Attribute Name	Type	Description
status	Integer	Execution result code, 0 represents success
message	String	Execution result explanation
size	Integer	Number of items returned in this request
total	Integer	Total number of data
total_pages	Integer	Total number of pages
item	Array	Chat log list, details of each element as follows

item

Attribute Name	Type	Description
id	Integer	Chat log ID
created_at	String	Chat creation time
sender	String	Initiator of the dialogue, values: "customer", "agent", "sys"
user_id	Integer	Sender's ID
content	String	Message content
session_id	Integer	ID of the session to which the message belongs
sub_session_id	Integer	ID of the sub-session to which the message belongs
survey_option_id	Integer	Selected option ID

Example

curl https://demo.udesk.cn/open_api_v1/im/sessions/log?email=admin@udesk.cn&sign_version=v2&nonce=1646275242&sign=f72ee9e4f1ef9c925e677538465a76b1be27cd74&timestamp=1646275242&session_id=4324143214&start_time=2022-03-03 00:00:00&end_time=2022-03-03 23:59:59&page=1&page_size=20

Return

{
    "status": 0,
    "message": "Success",
    "item": [
        {
            "id": 1234,
            "created_at": "2022-03-03 10:39:02",
            "sender": "agent",
            "user_id": 17,
            "content": "{\"type\":\"start_session\",\"data\":{\"content\":\"Customer service manually creates a conversation\"}}",
            "session_id": 123,
            "sub_session_id": 123456,
            "survey_option_id": null
        },
        {
            "id": 1235,
            "created_at": "2022-03-03 10:39:05",
            "sender": "agent",
            "user_id": 17,
            "content": "{\"type\":\"message\",\"font\":\"font-size:13px;font-weight:normal;font-style:normal;text-decoration:none;color:#1f1f1f;line-height:1.4;\",\"data\":{\"content\":\"demo message\",\"richContent\":\"demo message\"},\"platform\":\"web\",\"version\":2,\"seq_num\":\"\"}",
            "session_id": 123,
            "sub_session_id": 123456,
            "survey_option_id": null
        }
    ],
    "size": 2,
    "total": 2,
    "total_pages": 1
}

Fetch Satisfaction Survey Results

This interface is used to obtain satisfaction survey results for multiple specified time periods in one go. Rate limit: 1 time/2 seconds

Request Method

GET /im/sessions/vote

Request Parameters (Query String)

Parameter Name	Required	Description
start_time	No	Record start time: If no hour, minute, and second are passed, they default to 00:00:00. If not passed, it defaults to 00:00:00 of the query day.
end_time	No	Record end time: If no hour, minute, and second are passed, they default to 00:00:00. If not passed, it defaults to 24:00:00 of the query day.
page	No	Page number, starting from 1, default is 1
page_size	No	Number of items per page, default is 30, maximum is 1000

start_time and end_time query the creation time of satisfaction survey results; The format of start_time and end_time is "YYYY-MM-DD hh:mm:ss", or "YYYY-MM-DD" without time.

Response Data

Attribute Name	Type	Description
status	Integer	Execution result code, 0 represents success
message	String	Execution result explanation
size	Integer	Number of items returned in this request
total	Integer	Total number of data
total_pages	Integer	Total number of pages
item	Array	List of satisfaction survey results, see below for details of each element

Satisfaction Survey Results

Attribute Name	Type	Description
id	Integer	Unique identifier
created_at	Datetime	Creation time
session_id	Integer	ID of the session
sub_session_id	Integer	ID of the sub-session
survey_option_id	Integer	Selected option ID

Example

curl https://demo.udesk.cn/open_api_v1/im/sessions/vote?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

Return

{
  "status": 0,
  "message": "Success",
  "item": [
    {
      "id": 1,
      "created_at": "2015-01-01 12:00:00",
      "session_id": 1,
      "sub_session_id": 1,
      "survey_option_id": 1,
      "resolved_state": "0",
      "survey_remark": "Evaluation remarks",
      "tags": "Evaluation label"
    }
  ],
  "size": 1,
  "total": 1,
  "total_pages": 1
}

Data Structure - IM

IM Conversation Record

Attribute Name	Type	Description
sub_session_id	Integer	ID (same as im_sub_session_id)
session_id	Integer	Session ID
robot_session_id	Integer	Customer service system side robot session ID
note_id	Integer	Business record ID
customer_id	Integer	Customer ID
customer_name	String	Customer name
customer_custom_fields	Object	Customer custom fields, see below
agent_id	Integer	Customer service ID
agent_nick_name	String	Customer service name
resp_seconds	Integer	Response time, in seconds
queue_seconds	String	Queue time, in seconds
sustain_seconds	Integer	Duration
survey_vote_id	Integer	Satisfaction survey result ID
resolved_state	String	Satisfaction - whether resolved, values: "0", "1", meaning resolved, not resolved
platform	String	Channel, values: web, wechat, weibo, android, ios, api
web_info	Object	Browser visit information, see below
weixin_info	Object	WeChat visit information, see below
weibo_info	Object	Weibo visit information, see below
api_info	Object	API visit information
ios_info	Object	iOS SDK visit information
android_info	Object	Android SDK visit information
created_at	Datetime	Creation time
closed_at	Datetime	Closing time
close_method	String	Dialog end method, values: "agent_close", "redirect_close", "sys_close", "customer_close", meaning customer service closed, transferred closed, system closed, customer closed
belong_queue	String	Queue name
agent_msg_num	Integer	Customer service message count
customer_msg_num	Integer	Customer message count
source	String	Source
source_url	String	Source URL
queue_start_time	Datetime	Queue start time
conversations_num_today	Integer	Number of conversations today
search_keyword	String	Search keyword
custom_channel	String	Custom channel information
agent_invite_vote_count	Integer	Customer service invitation count
last_response	String	Last message sender, values: customer, agent, blank
alert_num	Integer	Alarm count
alert_desc	String	Alarm item
ticket_num	Integer	Work order count
ticket_nos	String	Work order numbers, separated by ","
im_web_plugin_id	Integer	Source plugin ID
sender	String	Initiator of the dialogue, values: customer, agent, sys
active_guest	String	Visitor invitation, values: agent, sys, blank, meaning customer service, automatic, none
ticket_ids	Array	Work orders corresponding to this conversation record
organization_id	Integer	Company ID
menu_names	String	Navigation menu names

Customer Browser Visit Information

Attribute Name	Type	Description
login_url	String
session_url	String
keyword	String
src	String
src_url	String	Same as source_url
sys	String
bowser	String
generated_channel	String
ip	String

WeChat Visit Information

Attribute Name	Type	Description
name	String	Customer WeChat nickname

Weibo Visit Information

Attribute Name	Type	Description
name	String	Customer Weibo nickname

API Visit Information

Attribute Name	Type	Description
from	String	Fixed as "API"

iOS SDK Visit Information

Attribute Name	Type	Description
phone_modal	String
phone_version	String
app_name	String
network_status	String
carrier	String
scale_screen	String

Android SDK Visit Information

Attribute Name	Type	Description
phone_modal	String
phone_version	String
app_name	String
network_status	String
carrier	String
scale_screen	String

IM Chat Log

Attribute Name	Type	Description
id	Integer	Unique identifier
created_at	Datetime	Creation date
sender	String	Sender identity, agent or customer
user_id	Integer	Sender ID
content	String	Message content
session_id	Integer	ID of the session to which the message belongs
sub_session_id	Integer	ID of the sub-session to which the message belongs
survey_option_id	Integer	Satisfaction survey result ID

Error Code Description

Error Code	Message Information	Exception:Message Information	Description
2000	No customer service is online	None	No customer service is available, cannot create a session
2065	Your company cannot call this interface, please contact udesk technical support	None	The current company has not enabled the "Send Message Preview" feature
9200	null	None	Required parameters are not filled in
	Robot parameter error	None	Incorrect parameter {robot_id} or {scene_id} value, no data found
	Missing parameter XXX, XXX	None	Required parameter {XXX} is not filled in
	Rating XXX for non-existent or deleted session	None	Required parameter {im_sub_session_id} is not filled in or no value matched
	Illegal rating	None	Required parameter {option_id} is not filled in
	Cannot rate repeatedly	None	The session corresponding to parameter {im_sub_session_id} has already been rated

Udesk API General Description

Fetch IM Conversation Records List

Request Method

Request Parameters (Query String)

Response Data

Example

Fetch IM Conversation Details

Request Method

Request Parameters (Query String)

Response Data

Example

Response

Fetch Chat Logs for a Specific Customer

Request Method

Request Parameters (Query String)

Response Data

Example

Response Data

Fetch Chat Logs List

Request Method

Request Parameters (Query String)

Response Data

Example

Fetch Satisfaction Survey Results

Request Method

Request Parameters (Query String)

Response Data

Satisfaction Survey Results

Example

Data Structure - IM

IM Conversation Record

Customer Browser Visit Information

WeChat Visit Information

Weibo Visit Information

API Visit Information

iOS SDK Visit Information

Android SDK Visit Information

IM Chat Log

Error Code Description

Products

Solutions

Resources