Custom Parameter Scheme Document for Mini Programs

Overview

Due to limitations within mini programs themselves, it is currently not possible to retrieve user information via API. Therefore, Udesk utilizes the session-from parameter supported by mini programs to achieve this functionality. The session-from parameter supports up to 1000 characters. To ensure normal usage, the length of this field should be kept <= 1000 bytes. It supports customer system information, custom fields, business titles, and business custom fields.

Configuration Method

1. Log in to the WeChat Mini Program platform at: https://mp.weixin.qq.com/
2. Go to Development->Basic Configuration to obtain Developer ID (AppID) and Developer Password (AppSecret).
3. Go to Udesk: Management Center->Channel Management->Mini Programs->Access WeChat Mini Program, fill in Developer ID and Developer Password.
4. Paste the generated URL address and Token into the mini program backend message push. Paste the randomly generated EcodingAESKey into the system, as well as paste APPSercret into the system.
5. User information can be obtained through this mini program.

Supported Fields

Field Explanation

Customer Field Reference

Business Record Field Reference

Parameter Name	Explanation
customer_name	Customer name, default is 'Mini Program User' (system field)
nick_name	Nickname
avatar	Avatar
email	Email
customer_token	Customer external unique identifier, equivalent to token
ip	IP
description	Customer description
organization_id	Company ID
tags	Tags
owner_id	Customer owner ID
owner_group_id	Customer owner group ID
level	Level
cellphones	Phone numbers, format is array, including parameters id (phone id), cellphone (phone number), id is empty when adding customer phone, non-empty when updating customer phone, format see example
other_emails	Other emails, format is array, including parameters id (email id), other_email (other email address), id is empty when adding customer email, non-empty when updating customer email, format see example
custom_fields	Custom fields
generated_channel	Custom channel name

Usage Instructions

Parameter Configuration

var customer_info = {
    "customer_name": "Customer Name", // Udesk system field
    "email": "test@udesk.cn", // Email
    "customer_token": 'test_token', // Customer external ID
    "generated_channel": 'Custom Channel Name',
    "ip": "192.168.1.1", // IP
    "description": "Description",
    "organization_id": 1, // Company ID
    "tags": "Tag1,Tag2", // Tags separated by comma
    "owner_id": 1, // Customer owner ID
    "owner_group_id": 1, // Customer owner group ID
    "level": "normal", // Level
    "cellphones": [
      ["", "13100000002"], // Array format [[phone ID, phone number]]
      ["3", "13100000003"] // When id is empty string or null, it means adding phone number; when it has value, it means updating the phone number corresponding to this id
      ], 
    "other_emails": [
      ["", "13100000002@udesk.cn"], // Array format [[email ID, email]]
      ["1", "13100000003@udesk.cn"] // When id is empty string or null, it means adding email; when it has value, it means updating the email corresponding to this id
      ], 
    "custom_fields": {
        "TextField_1": "Normal text content",
    }
}

var nick_name = "jack" // Mini program customer nickname
var avatar = "https://www.udesk.cn/images/index/logo1124.png" // Customer avatar

var note_info = {
    "title": "Business Record Title",
    "custom_fields": {
        "TextField_1": "Normal text content",
    }
}

var unionid = "ocpX10_1hQmCVGXzKrMwu-g7yuzU" // Mini program user unionid

// Convert to string
customer_info_str = JSON.stringify(customer_info)
note_info_str = JSON.stringify(note_info)

Inline Example

<!-- session-from = "udesk|Mini Program User Nickname|Avatar|customer^Customer Information|note^Business Record Information|unionid^Mini Program User Unionid" -->

<button open-type="contact" size="mini" session-from="udesk|{{nick_name}}|{{avatar}}|customer^{{customer_info_str}}|note^{{note_info_str}}|unionid^{{unionid}}">Enter Customer Session</button>

Help Center Access Instructions

http://udesk.udesk.cn/hc/articles/54089

Reference Example Code

https://github.com/wangmingle/weixin_mini_test.git

Behavioral Trajectory SDK

Before using, you need to open the behavioral trajectory. To open the behavioral trajectory, please contact the corresponding implementer. Udesk Mini Program SDK is used to collect customer's product browsing trajectory, order events, etc., and display them in IM Console > Session > Visitor Trajectory. If the mini program is not set in the Udesk customer service system, it needs to be set in [Management Center>Channel Management>Mini Programs - Access WeChat Mini Programs]

Obtaining and Using SDK

Download SDK After successful download, put the file in the root directory utils directory of the mini program, and import it in app.js import UdeskSdk from './utils/ud-sdk';

// Import sdk in app.js at the first line
import UdeskSdk from './utils/ud-sdk';

UdeskSdk.init({
  appId: 'xxxxxxxx',
  companyToken: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  companyDomain: 'xxx.udeskdemo.cn',
  onPageShow: function(){
    //do something
  }
});

Domain Setting

After logging in to the mini program background, we can see the AppID and server domain name in the menu "Development"-"Development Settings" (AppSecret must be configured)

Initialization

Method Explanation

UdeskSdk.init({ appId, companyToken, companyDomain, onPageShow, onPageHide });

Parameter Explanation

Parameter Name	Type	Value	Required	Explanation
appId	String		Yes	Mini program appId
companyToken	String		Yes	Company Mini Program authentication Token
companyDomain	String		Yes	Company domain, such as: xxx.udesk.cn
onPageShow	Function		No	Accepts page display event
onPageHide	Function		No	Accepts page hide event

> Product Browsing Trajectory Upload

Method Explanation

Call this function before initialization

UdeskSdk.trace(type, data);

Parameter Explanation

Parameter Name	Type	Value	Required	Explanation
type	String	product	Yes	Tracking type
data	Object		Yes	Tracking data
data.name	String		Yes	Product name
data.url	String		No	Product jump link (display in new page), if empty, cannot be clicked
data.imgUrl	String		No	If empty, not displayed
data.params	Object		No	Parameter list
data.params.text	String		No	Parameter text
data.params.color	String		No	Parameter color value, specified as hexadecimal color value (such as #ff0000)
data.params.fold	Boolean		No	Whether to bold
data.params.break	Boolean		No	Whether to wrap
data.params.size	Number	Default 12	No	Font size

Example

import UdeskSdk from './utils/ud-sdk';

UdeskSdk.trace('product', {
  name: " Apple iPhone X (A1903) 64GB Space Gray Mobile 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
  }]
});

> Order Event Upload

Method Explanation

Call this function before initialization

UdeskSdk.trace(type, data);

Parameter Explanation

Parameter Name	Type	Value	Required	Explanation
type	String	order	Yes	Tracking type
data	Object		Yes	Tracking data
data.order_no	String		Yes	Order number
data.name	String		Yes	Order name
data.url	String		No	Order jump link
data.price	Number		Yes	Order price
data.order_at	Date		Yes	Order placement time
data.pay_at	Date		No	Payment time
data.status	String		Yes	Order status: wait_pay (to be paid), paid (paid), closed (closed)
data.remark	String		No	Remarks, maximum length is 1000 bytes (2 bytes per Chinese character)
data.consignee_name	String		No	Consignee name
data.consignee_phone	String		No	Consignee phone number
data.commodit_num	String		No	Total number of products
commodities	Array		No	Product Information Array (Object)

commodities Product Information Object

Parameter Name	Type	Required	Explanation
commodit_name	string	No	Product name
commodit_no	string	No	Product number
commodit_count	numeric	No	Product quantity
commodit_fee	string	No	Product price

Example

import UdeskSdk from './utils/ud-sdk';

UdeskSdk.trace('order', {
  order_no: "1000",
  name: "First Order",
  url: "https://xxx.xxxx.com/order link",
  price: 16.8,
  order_at: new Date(),
  pay_at: new Date(),
  status: "wait_pay",
  remark: "Remarks up to 1000 bytes",
  consignee_name: 'jack',
  consignee_phone: '01012345',
  consignee_address: 'Beijing, Daxing District',
  commodit_num: 88,
  commodities: [
    {
      commodit_name: 'Milk A',
      commodit_no: 'NO123456',
      commodit_count: 1,
      commodit_fee: '46.5'
    }
  ]
});