logo
  • Home
  • API
  • Third-Party Integration
  • Chatbot
  • CallCenter PaaS API
  • Voicebot

Basic Usage

Log in to the Udesk customer service system administrator account, navigate to Management Center -> Channel Management -> Instant Messaging -> Web Plugin -> (specific plugin) Management, configure the basic properties, then copy the code to your webpage to enable Udesk IM.

Considerations

Device Support

WebIM currently supports devices such as PC/Android (including tablets)/IOS (including tablets).

Browser Compatibility

WebIM currently supports IE8+ (inclusive) and other mainstream browsers based on its core (360/qq/...), as well as other mainstream browsers (chrome/firefox/...).

Basic Example

Embedded Code Example

<body>
    <!-- Webpage content. Copy the code from the administrator's instant messaging webpage plugin here. -->

    <script>
    (function(a,h,c,b,f,g){a["UdeskApiObject"]=f;a[f]=a[f]||function(){(a[f].d=a[f].d||[]).push(arguments)};g=h.createElement(c);g.async=1;g.src=b;c=h.getElementsByTagName(c)[0];c.parentNode.insertBefore(g,c)})(window,document,"script","https://xxx.xxxx.cn/im_client/js/udeskApi.js?1487931175918","ud");
    ud({
        "code": "xxxx",
        "link": "https://xxx.xxxx.cn/im_client/?web_plugin_id=1",
        "isInvite": true,
        "mode": "inner",
        "color": "#307AE8",
        "pos_flag": "srb",
        "language": "en-us", // Language - English
        "onlineText": "Contact Customer Service, Online Consultation",
        "offlineText": "Customer Service Off Duty, Please Leave a Message",
        "mobile": {
            "mode": "blank",
            "color": "#307AE8",
            "pos_flag": "crb",
            "onlineText": "Contact Customer Service, Online Consultation",
            "offlineText": "Customer Service Off Duty, Please Leave a Message"
        }
    });
    </script>
</body>

Link Example

https://xxx.xxxx.cn/im_client/?web_plugin_id=xx&language=zh-cn&agent_id=xxx&group_id=xxx

Custom Configuration

Developers can customize related configurations according to their needs. All properties and events are configured within ud({...}), and all methods are called using ud(methodName, ...arguments).

Configuration Method

  1. ud({key: val, key2: val2, ...});
  2. ud(key, val);

Parameter Explanation

Global Parameters

Parameter NameTypeValueRequiredDescription
codeStringSystem-generatedYesCompany unique identifier
linkStringSystem-generatedYesCompany IM Client link
isInviteBooleantrue or false (default)NoWhether to enable visitor invitation function
agent_idStringSpecified agent ID, default unspecifiedNoSpecify the customer service agent for the session
group_idStringSpecified group ID, default unspecifiedNoSpecify the customer service group for the session
session_keyString6-character random stringNoDifferent session_key for the same client triggers a new session. Only letters, numbers, and underscores are supported
merchant_idStringMerchant IDNoIf passed, both session_key and merchant_id need to transmit the same merchant ID
Session logic: passing stores related parameters, do not disrupt the current session order, robot, pre-consultation form, messages, etc., only save parameters during manual session and display replacement
merchant_nameStringMerchant nameNoIn the session with the customer service, the "customer service introduction" will be replaced by "merchant name"
merchant_avatarStringMerchant avatarNoIn the session with the customer service, the "customer service avatar" will be replaced by "merchant avatar"
merchant_listBooleantrue or false (default)NoWhen merchant_list=true in the webpage plugin link, the webpage plugin loads all the merchants in the current customer's history sessions, sorted by the latest session time for each merchant
modeStringinner: embedded mode (default)
blank: standalone window mode		NoButton opens window display mode.
Configurable in the management console
colorStringButton color code, default: #307AE8NoConfigure IM button color.
Configurable in the management console
pos_flagStringButton shape + position
1) Shape: h(horizontal) v(vertical) c(circular) i(image);
2) Position: lt(left top) mt(mid top) rt(right top) lm(left middle) mm(middle) rm(right middle) lb(left bottom) mb(mid bottom) rb(right bottom)
Default: crb (pc), hrb (mobile)		NoButton shape + position
Example: vrb (vertical right bottom)
Image configuration path: Management Center - Channel Management - Instant Messaging - Web Plugin - Management - Button Settings
onlineTextStringDisplay text when customer service is online, default: "Contact Customer Service, Online Consultation"YesConfigurable in the management console
offlineTextStringDisplay text when customer service is offline, default: "Customer Service Off Duty, Please Leave a Message"YesConfigurable in the management console
noBubbleBooleantrue or false (default)NoDo not display message pop-up bubble reminders
manualInitBooleantrue or false (default)NoManual initialization. When set to true, the embedded code will not initialize automatically and needs to be called actively using the ud('init') method
languageString"zh-cn" (Chinese) or "en-us" (English)NoConfigure client multilingualism [Details]
channelStringCustom channelNoConfigurable in the management console
targetSelectorStringSupports #id,.class,tagName,...
Default system-generated Unique		NoMain target button selector
1) Used to trigger the chat window
2) Used to replace the default system-provided button, specifying valid defaults no longer display
3) Used to receive invitations
4) Used to receive new message reminders
5) ...
selectorStringSupports #id,.class,tagName,...
Default none Multiple possible		NoAuxiliary button selector
1) Used to trigger the chat window
cssObjectButton custom style, such as: css:{top:10%}, default noneNo
windowObjectStandalone window mode only Standalone window default size is width 780, height 560
Example window: {"width": "780", "height": "560"}		NoConfigure the size of the opened standalone window
panelObjectWebpage embedded mode onlyNoSession panel [Details]
popObjectNoMessage reminder bubble [Details]
customerObjectNoCustomer information [Details]
productObjectNoConsultation object [Details]
hide_productBooleanNoWhen the parameter is true, the display of the client's consultation object will be hidden, and the customer service side will still display
mobileObjectNoMobile-related configuration [Details]
When the website is responsive layout, provide customization for pc and mobile
robot_modelKeyStringRobot FAQ template IDNoCall the common problem template according to the robot common problem template ID, you can view it in 'Km-Robot-FAQ dialogue-Knowledge base-Common problem-ID'
c_cf_dialogueDescStringCustom value, supports multiple values separated by commasNoThe purpose of this field is to meet the needs of customers to pass any custom information to the robot
Usage: First, you need to set a custom field named c_cf_dialogueDesc in the customer custom field in the customer service system. After setting the customer's field value, open the web IM webpage plugin and add the field to the path parameter. The format is as follows https://xxx.udesk.cn/im_client/?web_plugin_id=41597&c_cf_dialogueDesc=* This way, the system will automatically pass the value of c_cf_dialogueDesc to the robot, and the robot's dialogue description field will receive this value
uba{app_key: string}User behavior analysis configurationNoExample: ud(\{uba:{app_key: 'xxxxxxx'\}})
src_urlStringhttp URL addressNoSource URL

Example

ud({
    "code": "xxxx",
    "link": "https://xxx.xxxx.cn/im_client/",
    "mode": "inner",
    "color": "#307AE8",
    "pos_flag": "srb",
    "onlineText": "Contact Customer Service, Online Consultation",
    "offlineText": "Customer Service Off Duty, Please Leave a Message",
    "targetSelector": "#btn_udesk_im",
    "selector": ".udesk_im",
    "pop": {},
    "panel": {},
    "mobile": {},
    "window": {}
});

> Mobile - Parameter Explanation

Parameter NameTypeValueRequiredDescription
modeStringinner: embedded mode (default)
blank: standalone window mode		NoButton opens window display mode.
Configurable in the management console
colorStringButton color code, default: #307AE8NoConfigure IM button color.
Configurable in the management console
pos_flagStringButton shape + position
1) Shape: h(horizontal) v(vertical) c(circular) i(image);
2) Position: lt(left top) mt(mid top) rt(right top) lm(left middle) mm(middle) rm(right middle) lb(left bottom) mb(mid bottom) rb(right bottom)
Default: crb (pc), hrb (mobile)		NoButton shape + position
Example: vrb (vertical right bottom)
Image configuration path: Management Center - Channel Management - Instant Messaging - Web Plugin - Management - Button Settings
onlineTextStringDisplay text when customer service is online, default: "Contact Customer Service, Online Consultation"YesConfigurable in the management console
offlineTextStringDisplay text when customer service is offline, default: "Customer Service Off Duty, Please Leave a Message"YesConfigurable in the management console
noBubbleBooleantrue or false (default)NoDo not display message pop-up bubble reminders
languageString"zh-cn" (Chinese) or "en-us" (English)NoConfigure client multilingualism
targetSelectorStringSupports #id,.class,tagName,...
Default system-generated Unique		NoMain target button selector
1) Used to trigger the chat window
2) Used to replace the default system-provided button, specifying valid defaults no longer display
3) Used to receive invitations
4) Used to receive new message reminders
5) ...
selectorStringSupports #id,.class,tagName,...
Default none Multiple possible		NoAuxiliary button selector
1) Used to trigger the chat window
cssObjectButton custom style, such as: css:{top:10%}, default noneNo
popObjectNoMessage reminder bubble [Details]

Example

ud({
    "mobile", {
        "mode": "blank",
        "color": "#307AE8",
        "pos_flag": "crb",
        "onlineText": "Contact Customer Service, Online Consultation",
        "offlineText": "Customer Service Off Duty, Please Leave a Message",
        "pop": {
            "direction": "top",
            "arrow": {
                "top": 0,
                "left": "70%"
            }
        }
    }
});

> Session Panel - Parameter Explanation

Parameter NameTypeValueRequiredDescription
cssObjectCustom style, such as: css:{top:10%}, default noneNoPanel position only supports top, left, right
onToggleFunctionCustom method
Parameter: data.visible (true or false)},		NoCheck whether the current session panel is open. When visible is true, it is open

Example

ud({
    "panel": {
        "css": {
            "top": "0",
            "left": "0"
        },
        "onToggle": function(data) {  //Panel switch time
            if (data.visible) {
                //console.log('Window open');
            }
            else{
                //console.log('Window closed');
            }
        }
    }
});

> Message Reminder Bubble - Parameter Explanation

Parameter NameTypeValueRequiredDescription
cssObjectCustom style, such as: css:{top:10%}, default noneNo
directionStringBubble pop-up direction, "top" (default); "right"; "left"; "bottom"No
offsetObjectBubble offset, {top:0,left:0}, default relative center displayNo
arrowObjectBubble arrow configuration, {top:0,left:0}, default relative center displayNo

Example

ud({
    "pop": {
        "direction": "top",
        "arrow": {
            "top": 0,
            "left": "70%"
        }
    }
});

Sure! Here's the translation of the provided markdown document:

Customer Information - Parameter Description

Overview

When website logged-in users chat via web im, they can transfer customer information to Udesk through links. This allows customer service to directly view customer information while chatting with customers. The customer information assistant component can further help understand other information about this customer, such as orders.

Usage

Add parameters and encrypted information to the link (https://xxxx.udesk.cn/im_client/) in the web im conversation window according to the following rules to transmit customer information.

The email and phone number are used for customer identification, that is, they are compared with existing data in the Udesk system's CRM. If it is an existing customer, the information will be updated; if there is no match, a new customer will be created.

Customer Authentication - Request Parameters

Identity authentication is required to pass customer information and business records signature encryption algorithm. If you do not need to pass this data, identity authentication is not required;
Validity period of customer identity recognition: 4 days;
Order of customer identity recognition: web_token > customer_token > c_email > c_phone;
If the passed web_token or customer_token does not exist in the system; but the passed c_email or c_phone exists, the system will still recognize it as an existing customer. If only web_token is passed without passing customer_token, c_email, c_phone, etc., identity data, web_token will only match one data of the customer's web_token. If no match is found, a new customer will be created.

Parameter NameTypeValueRequiredDescription
nonceStringRandom numberYesA random number, dynamically generated, provides higher security than static random numbers.
timestampStringTimestampYesCurrent timestamp (13 milliseconds).
web_tokenStringCustomer IDYesUnique identifier for the customer, recommended to use email, phone number, etc. Only letters, numbers, and underscores are supported, special characters are disabled
customer_tokenStringExternal customer IDNoExternal unique identifier for the customer, equivalent to open_api_token Only letters, numbers, and underscores are supported, special characters are disabled
signatureStringEncrypted signatureYes[Signature encryption algorithm]
encryption_algorithmStringSHA1 or SHA256NoEncryption algorithm, defaults to SHA1 if not specified, SHA256 recommended

Signature Encryption Algorithm (Three Steps)

  1. Concatenate characters according to the parameters and order behind: nonce, timestamp, web_token, im_user_key in the form of key=value&
    im_user_key acquisition location [Management Center-Instant Messaging-Web Plugins-Management/Adding Customer Information KEY]

sign_str = nonce=value&timestamp=value&web_token=value&im_user_key

  1. Use the encryption algorithm to calculate the signature string

sign_str = sha1(sign_str)
or sign_str = sha256(sign_str)

  1. Convert the string to uppercase

sign_str = sign_str.toUpperCase()

  1. Common mistakes reminder

  2. im_user_key requires only values ​​without parameters

  3. The signature string should be converted to uppercase

SHA1 Example:
    sign_str = "nonce=9ca6fff5a509fb887ac72cf5c92010e7&timestamp=1455675719000&web_token=test@udesk.cn&b476f9f8-5309-4d0a-a2d4-af08c4507a15";
    sign_str = sha1(sign_str);
    sign_str = sign_str.toUpperCase();

Examples

// SHA1 Example
ud({
    "customer": {
        "nonce": "9ca6fff5a509fb887ac72cf5c92010e7",
        "signature": "9B2619225AA6476DC1EB80DBB8801E1575EBE39C",
        "timestamp": "1455675719000",
        "web_token": "test@udesk.cn"
    }
});

// SHA256 Example
ud({
    "customer": {
        "nonce": "9ca6fff5a509fb887ac72cf5c92010e7",
        "signature": "4CC40FA2D762DAB1D4509750A7135123743D26F2552B7E23611AB8CB5D35825B",
        "timestamp": "1455675719000",
        "web_token": "test@udesk.cn",
        "encryption_algorithm": "SHA256"
    }
});

Customer Parameters

Parameter NameTypeValueRequiredDescription
c_nameStringCustomer nameNo
c_emailStringCustomer emailuniqueNo
c_phoneStringCustomer phone numberuniqueNo
customer_tokenStringExternal customer identifieruniqueNoThe same field as open_api_token
c_descStringCustomer descriptionNo
c_orgStringCompany nameNoIf multiple companies are opened, multiple ones are supported, separated by commas in English such as: "handsome, beautiful"; if not opened, only the first one is taken
c_tagsStringCustomer tagsNoPass customer tags, separated by commas such as: "handsome, beautiful"
c_ownerStringCustomer owner IDNo
c_vipString'vip'(VIP customer) or 'normal'(ordinary customer)NoCustomer VIP identification
c_owner_groupStringCustomer responsible group IDNo
c_other_emailsStringOther customer email listNoSeparated by commas such as: "a@xxx.cn, b@xxx.cn"
c_cf_<custom field name>StringCustomer custom fieldNoCustomer custom field such as: c_cf_name, c_cf_age, ...

Business Record - Request Parameters

Parameter NameTypeValueRequiredDescription
c_cn_titleStringRecord subjectNoPass the record subject
c_cn_<custom field name>StringRecord custom fieldNoRecord custom field such as: c_cn_name, c_cn_age, ...

Examples

ud({
    "customer": {


        "c_name": "Customer Name Kimi",
        "c_email": "newest3@udesk.cn",
        "c_other_emails": '11@udesk.cn,22@udesk.cn',
        "c_desc": "Intentional customer, huge potential",
        "c_org": "desc",
        "c_phone": "1100110012",
        "c_tags": "handsome, newly added",
        "c_owner_group": "62",
        "c_owner": "3",
        "c_vip": "vip",
        "c_qq": "123123",
        "c_cf_aget": 10,
        "c_cf_like": "Extreme Challenge",
        "c_cn_title":"Record subject",
        "c_cn_name":"Record name",
        "nonce": "694db2645b3f69a8",
        "signature": "315345C77C73A128CF9850EAD777F7A71D423A36",
        "timestamp": "1465878579000",
        "web_token": "newest3@udesk.cn"
    }
});

Link Example

Encode the passed parameters, otherwise, they may appear as garbled!

https://xxx.udesk.cn/im_client/?c_desc=test123456789&c_email=jiangst%40udesio.com&c_phone=15888888888&echostr=hello&nonce=cdebd5d13f4d331e&signature=693140534BDDDAF002A46F0027E06244DF0B21AB&timestamp=1457696747000&web_token=42f6607e-8892-4fcf-889b-f9babf627060

Ticket Information - Request Parameters

Parameter NameTypeValueRequiredDescription
t_subjectStringTicket subjectNoTicket subject
t_contentStringTicket descriptionNoIf passed, it will be included on the page and will overwrite the message content template
t_priority_idStringTicket priorityNot_priority_id range 1 (urgent), 2 (high), 3 (standard), 4 (low) Details
t_status_idStringTicket statusNot_status_id range 1 (open), 2 (resolved), 3 (closed), 4 (in progress) Details
t_tagsStringTicket tagsNoPass ticket tags, separated by commas such as: "tag1, tag2, tag3"
t_cf_<custom field name>StringTicket custom fieldNoTicket custom field, get field details list through API such as: t_cf_TextField_213, t_cf_SelectField_225 Details

Examples

ud({
    "ticket": {
        "t_subject": "Ticket subject",
        "t_content": "Ticket description",
        "t_priority_id": '3',//standard
        "t_status_id": "1",//open
        "t_tags": "Sound of Thunder, But Hope for Rain, Can Keep You Here",
        "t_cf_TextField_213": "Text",
        "t_cf_TextField_214": "12:00:00",//time
        "t_cf_TextField_215": "2018-10-26",//date
        "t_cf_TextField_215": "2018-10-20 12:00",//datetime
        "t_cf_SelectField_225": "3",//single select or dropdown
        "t_cf_SelectField_226": "1,2",//multi-select
        "t_cf_SelectField_227": "0,0",//cascading
    }
});

Link Example

Encode the passed parameters, otherwise, they may appear as garbled!

https://xxx.udesk.cn/im_client/?t_priority_id=3&t_status_id=1&t_cf_TextField_124=%E6%96%87%E6%9C%AC%E6%A1%86&t_cf_TextField_135=2018-10-20&t_cf_TextField_136=12:00:00&t_cf_TextField_137=2018-10-20%2012:00&t_cf_TextField_138=3.14&t_cf_TextField_139=250&t_cf_TextField_140=https://www.baidu.com&t_cf_TextField_141=abc&t_cf_TextField_142=%E9%80%9A%E5%8E%BF&t_cf_SelectField_134=1&t_cf_SelectField_135=0,0&t_cf_SelectField_136=0&t_cf_SelectField_137=1,2&t_tags=%E6%B5%8B%E8%AF%951,%E5%BC%A0%E4%B8%89,%E6%9D%8E%E5%9B%9B,%E7%8E%8B%E4%BA%94&c_name=im_client%E6%B5%8B%E8%AF%95%E5%AE%A2%E6%88%B7&c_email=t_im_client@163.com&c_phone=13520361010

Consultation Object - Parameter Description

Two access methods are provided: URL parameter method, JavaScript access method

Parameter Description

NameValueDescription
titleStringTitle
title_styleStringTitle style, for example: color:rgb(50,50,50);font-weight:bold
urlStringLink to the landing page
imageStringDisplay image address
sendtrue or falseWhen true, a send button will appear below the consultation object. Clicking send will send the current consultation object as a product message to the customer service
<custom parameter>Multiple custom parameters can be defined, can be in Chinese
<custom parameter>_styleStringCustom parameter style

URL Parameter Method

Add the prefix product_ in front of all parameters. Encode the passed parameters, otherwise, they may appear as garbled!

Example: https://udeskdemo.udesk.cn/im_client/?product_send=true&product_title=Apple%20iPhone%207&product_url=http%3A%2F%2Fitem.jd.com%2F3133829.html%3Fcu%3Dtrue%26utm_source%E2%80%A6erm%3D9457752645_0_11333d2bdbd545f1839f020ae9b27f14&product_image=http%3A%2F%2Fimg14.360buyimg.com%2Fn1%2Fs450x450_jfs%2Ft3157%2F63%2F1645131029%2F112074%2Ff4f79169%2F57d0d44dN8cddf5c5.jpg%3Fv%3D1474635884816&product_%E4%BB%B7%E6%A0%BC=%EF%BF%A56189.00&product_%E4%BF%83%E9%94%80%E4%BF%A1%E6%81%AF=%E8%B4%AD%E4%B9%B0%E4%BA%AC%E4%B8%9C%E8%87%AA%E8%90%A5%E7%94%B5%E8%84%91%2C%E6%89%8B%E6%9C%BA%2C%E6%95%B0%E7%A0%81%E5%93%81%E7%B1%BB%E6%8C%87%E5%AE%9A%E4%BA%A7%E5%93%81%2C%E5%AE%9E%E9%99%85%E4%B8%8B%E5%8D%95%E7%BB%93%E7%AE%97%E9%87%91%E9%A2%9D%E6%BB%A1199%E5%85%83%2C%E8%BF%94%E4%BA%AC%E4%B8%9C%E8%87%AA%E8%90%A5%E5%A4%A7%E9%97%B8%E8%9F%B9%E4%B8%9C%E5%88%B8%E4%B8%80%E5%BC%A0.

JavaScript Access Method

ud({
    product: {
        title: "Apple iPhone 7",
        url: "http://item.jd.com/3133829.html?cu=true&utm_source…erm=9457752645_0_11333d2bdbd545f1839f020ae9b27f14",
        image: "http://img14.360buyimg.com/n1/s450x450_jfs/t3157/63/1645131029/112074/f4f79169/57d0d44dN8cddf5c5.jpg",
        "price": "￥6189.00",
        "Promotional price": "￥6188.00"
   }
});

Configuration of Client-Side Multilingual Support - Details

Finding Configured Language Codes from Multilingual Configuration

Multilingual feature needs to be enabled separately by contacting Udesk

Management -> Account Settings -> Multilingual Support

Language NameFile NameLanguage CodeUpdate DateAction
Englishreocar_language_translation(en-us).xlsxen-us2017/08/23 14:30Download File
Upload File
Update

Select the language code en-us configured as the parameter for the language. If you need to use French, you need to first configure the multilingual for French, and then use the language code from the 'French Configuration Record' in the multilingual support list.

zh-cn (Simplified Chinese) is already the system default and can be used directly without configuring it in 'Multilingual Support.'

If a language code parameter is passed that is not configured in the 'Multilingual Support List,' the default Simplified Chinese will be used.

The displayed content in frontend static resources now supports Simplified Chinese and English, and does not support custom language translation. If you need support for more languages, please contact us.

Multilingual Language Code Configuration Rules

Language codes can only be selected from the following list:

If the desired multilingual language code is not in the list below, please contact Udesk.

Language NameLanguage Code
Arabicar
Englishen-us
Spanishes
Frenchfr
Japaneseja
Koreanko
Thaith
Indonesianid
Traditional Chinesezh-TW
Portuguesept
Russianru

Method Description

Method NameParameterDescription
initNoneManual initialization, but effective when manualInit is set to true. Example: ud("init")
hidePanelNoneManually hide the session panel. Example: ud("hidePanel")
showPanelNoneManually open the session panel. Example: ud("showPanel")
dataTracetype (Data type), data (Data)Data tracking including browsing history, events, etc.

Product Browsing History Upload

Method Description

ud("dataTrace", type, data);

Parameter Description

Parameter NameTypeValueRequiredDescription
typeStringproductYesTracking type
dataObjectYesTracking data
data.nameStringYesProduct name
data.urlStringNoProduct redirect link (opens in new page). Cannot be clicked if value is empty.
data.imgUrlStringNoImage URL. Will not display if value is empty.
data.paramsObjectNoParameter list
data.params.textStringNoParameter text
data.params.colorStringNoParameter color value, specified as hexadecimal color (e.g., #ff0000)
data.params.foldBooleanNoWhether it's bold
data.params.breakBooleanNoWhether it's line break
data.params.sizeNumberDefault 12NoFont size

Example

// Product browsing history
ud("dataTrace", "product", {
    "name": " Apple iPhone X (A1903) 64GB Space Gray Mobile Unicom 4G Phone",
    "url": "https://item.jd.com/6748052.html",
    "imgUrl": "http://img12.360buyimg.com/n1/s450x450_jfs/t10675/253/1344769770/66891/92d54ca4/59df2e7fN86c99a27.jpg",
    "params": [
        {
            "text": "￥6999.00",
            "color": "#FF0000",
            "fold": false,
            "break": false,  //break is a keyword, should be wrapped in quotes for IE8
            "size": 12
        }
    ]
});

Order Event Upload

Order event upload requires prior customer authentication, and then can be called using the following methods.

Method Description

ud("dataTrace", type, data);

Parameter Description

Parameter NameTypeValueRequiredDescription
typeStringorderYesTracking type
dataObjectYesTracking data
data.order_noStringYesOrder number
data.nameStringYesOrder name
data.urlStringNoOrder redirect link
data.priceNumberYesOrder price
data.order_atDateYesOrder placement time
data.pay_atDateNoPayment time
data.statusStringYesOrder status: wait_pay (pending payment), paid (paid), closed (closed)
data.remarkStringNoRemark, maximum length is 1000 bytes (Chinese counts as 2 bytes)
data.consignee_nameStringNoConsignee name
data.consignee_phoneStringNoConsignee phone
data.commodit_numStringNoTotal number of commodities
commoditiesArrayNoCommodity Information Array (Object)

Commodities Object for Product Information

Parameter NameTypeRequiredDescription
commodit_namestringNoProduct name
commodit_nostringNoProduct number
commodit_countnumericNoProduct quantity
commodit_feestringNoProduct price

Example

ud("dataTrace", "order", {
    order_no: '1',
    name: 'First Order',
    url: 'http://xxx.xxxx.com/order-link',
    price: 16.8,
    order_at: new Date(),
    pay_at: new Date(),
    status: 'wait_pay',
    remark: 'Remark',
    consignee_name: 'tom',
    consignee_phone: '01012345',
    consignee_address: 'Beijing, China',
    commodit_num: 88,
    commodities: [
      {
        commodit_name: 'Milk A',
        commodit_no: 'NO123456',
        commodit_count: 1,
        commodit_fee: '46.5'
      }
    ]
});

Marketing Session Event Tracking

Method Description

ud("dataTrace", type, data);

Parameter Description

Parameter NameTypeValueRequiredDescription
typeStringmarketingYesTracking type
dataObjectYesTracking data
data.nameStringYesEvent name

Example

// Cancel Order
ud("dataTrace", "marketing", {
    "name": "Cancel Order"
});

Event Description

Parameter NameTypeValueRequiredDescription
onReadyFunctionListening event, no parametersNoCallback for Udesk IM plugin initialization completion
onUnreadFunctionListening event, parameters: data:{count:1 //unread message count}NoCallback for unread message event

Example

ud({
    "onReady": function() {
        console.log('Initialization complete');
    },
    "onUnread": function(data) {
        console.log('Unread message count: ' + data.count);
    }
});

> Button Position Modification (Drag and Drop)

Overview

Mainly used for third-party modification of button positions to implement custom drag and drop events. Modify the CSS (top, right, bottom, left) of class udesk-client-btn.

Notes

To prevent dragging clicks from triggering events such as expanding session templates or accepting invitations, you need to: Call ud('noDrag') in the document.onmousedown event. Call ud('isDrag') in the document.onmousemove event.

Example

  1. Modify button position: Customer Service System Backend -> Channel Management -> Instant Messaging -> Web Plugin (Click Manage) -> Button Settings (Top Right)
  2. Drag and drop modification method: Implemented by the user. You can use native mousemove and mouseup methods, depending on your actual business logic.

Window Settings - Custom URL for Information Area

When using the Udesk web plugin and configuring a custom URL in the window settings of the plugin, you can send messages to Udesk customer service/robots on the configured page.

Basic Usage

The custom URL page communicates with the parent page through postMessage and needs to follow a specific message format.

Customer service chat interface: Can send text messages and product messages. Robot chat interface: Only supports sending text messages.

Passing Current Window Web Page Link to Custom iframe

The window will pass the parameters of the current web page link to the custom URL's iframe. (Among these four parameters, cur_url, cur_title, pre_url, src_url are not passed.)

Parameter Description

Parameter NameTypeValueRequiredDescription
methodString'sendMsg'YesMethod name, currently only supports sendMsg
typeString'text' or 'product'YesMessage type: text message or product message
contentString or ObjectYesMessage content

Example

  1. Text Message
    var data = JSON.stringify({
            method: "sendMsg",   // Fixed method
            type: "text",        // Fixed type
            content:  “xxx”      // Message to be sent
        });
    var origin = "*";
    window.parent.postMessage(data, origin);
  1. Product Message Parameter Details
    var data = JSON.stringify({
            method: "sendMsg",      // Fixed method
            type: "product",        // Fixed type
            content: {              // Product message format
                name: "Apple iPhone X (A1903) 64GB Space Gray Mobile Unicom 4G Phone",
                url: "https://item.jd.com/6748052.html",
                imgUrl: "http://img12.360buyimg.com/n1/s450x450_jfs/t10675/253/1344769770/66891/92d54ca4/59df2e7fN86c99a27.jpg",
                params: [{
                    text: "￥6999.00",
                    color: "#FF0000",
                    fold: false,
                    break: false,
                    size: 12
                }, {
                    text: "Add 30 yuan for orders over 1999 yuan"
                }]
            }
        });
    var origin = "*";
    window.parent.postMessage(data, origin);

Notes

  1. Please limit the sending frequency.
  2. Pay attention to the message format.

Custom Search Keywords

Parameter NameTypeDescription
udesk_wdStringSearch keyword, passed from third party like Baidu promotion

Third Party Website Link Example (e.g., Company Official Website)

https://www.companydomain.com?udesk_wd=xxxx

Web Plugin Link Example

https://companydomain.udesk.cn/im_client/?udesk_wd=xxxx

Transmitting Events to External Sources

The web plugin sends events to external sources via window.postMessage.

Third-party pages receive them by using window.addEventListener('message',function (event) \{ //event \}).

Example

    window.addEventListener('message',function (event) {
        /*
            Example: Handling session end event
            Differentiate event types using the received type, see parameter details for specific event types
        */
        let receiveEvent = JSON.parse(event.data)
        if (receiveEvent.type === 'chatDone') {
            // Custom event
        }
    })
ValueDescription
chattingSession start event
chatDoneSession end event
queuingEntering queue event
hidePanelHide window event
marketing@udeskglobal.com

Products

Solutions

Resources