Udesk-Customer service solution leader

Basic Information

Udesk provides a unique WeChat Official Account access solution that does not require Udesk to obtain WeChat Official Account permissions. Instead, it involves developing middleware to obtain WeChat Official Account permissions and forward messages and events that fit the customer service scenario to Udesk.

For developers of the middleware, the following scenarios need to be handled.

Receiving messages from the WeChat server, forwarding them to the UDESK system, and passing the return from the UDESK system back to the WeChat server.
Receiving requests from the UDESK system, forwarding them to the WeChat server, and passing the return from the WeChat server back to the UDESK system.

When receiving a POST request with no query parameters, it is considered as a message push.
When receiving a POST request with a 'type=TYPE' query parameter, it is considered as uploading multimedia messages (i.e., adding temporary materials).
When receiving a GET request with a 'media_id=MEDIA_ID' query parameter, it is considered as requesting to obtain multimedia messages (i.e., obtaining temporary materials).
When receiving a GET request with an 'openid=OPEN_ID' query parameter, it is considered as requesting to obtain user basic information.

Note: When the UDESK system pushes messages to the simulated middleware, it does not include the appid. If a customer has multiple official accounts accessing, it is recommended to set the simulated domain name in the following format:

1. http://udesk.simulate_weixin.com/APPID
2. http://udesk.simulate_weixin.com?appid=APPID

1. Receiving Messages

When the WeChat server sends a message to the simulated middleware, the simulated middleware forwards the message sent by WeChat to the UDESK system and passes the return from the UDESK system back to the WeChat server.

Request Description

Initiator	Receiver	Request Method
Simulated Middleware	UDESK System	POST

POST 'URL provided by UDESK'

Note: Location of the URL: "Management Center - Channel Management - WeChat - Management" in "URL"

Request Parameters

The request parameters here should be consistent with WeChat Developer Documentation - Message Management - Receiving Standard Messages.

Return Value

There are two types of returns from the UDESK system. For these two return scenarios, the simulated middleware can directly pass them back to the WeChat server.

Empty string, ""
Specific XML-structured information, see WeChat Developer Documentation - Passive Reply to User Messages for details.

Example

# Example of calling
curl udesk.udesk.com/weixin/olloowpoeakkskknx0ijm -d '{
<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>1348831860</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[this is a test]]></Content>
  <MsgId>1234567890123456</MsgId>
</xml>
}'

<!-- Example of return -->
<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>12345678</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[Hello]]></Content>
</xml>

2. Pushing Messages

When the UDESK system pushes messages to the simulated middleware, the simulated middleware requests the WeChat server's "Custom Service Message - Send Message" interface and passes the return from the WeChat server to the UDESK system.

The simulated middleware needs to convert the content in the request body into JSON format before passing it to the WeChat server.
For the method of pushing messages from the simulated middleware to the WeChat server, see WeChat Developer Documentation - Custom Service Message - Custom Interface. Sending Messages

Initiator	Receiver	Request Method
UDESK System	Simulated Middleware	POST

Request Description

POST 'Simulated domain name address filled in by the customer'

Note: Location of simulated domain name configuration: "Management Center - Channel Management - WeChat - Management" in "Simulated Domain Name"

Request Parameters

Send text message

Parameter	Description
touser	Customer's openid
msgtype	Message type, here is 'text'
text[content]	Message content

Send image message

Parameter	Description
touser	Customer's openid
msgtype	Message type, here is 'image'
image[media_id]	Multimedia message ID

Send voice message

Parameter	Description
touser	Customer's openid
msgtype	Message type, here is 'voice'
voice[media_id]	Multimedia message ID

Send video message

Parameter	Description
touser	Customer's openid
msgtype	Message type, here is 'video'
video[media_id]	Multimedia message ID

Send news message

Parameter	Description
touser	Customer's openid
msgtype	Message type, here is 'news'
news[articles]	News message content, an array

Details of articles

Parameter	Description
title	Title
description	Description
url	External link address
picurl	Image address

Return Value

See the return value of WeChat Developer Documentation - Custom Service Message - Custom Interface. Sending Messages

The simulated middleware needs to pass the return value from the WeChat server to the UDESK system, and the UDESK system will determine whether the message is successfully sent based on the return value.

Example

# Example of calling, using text message as an example
# Content-Type : application/x-www-form-urlencoded
curl www.simulate_weixin.com -d 'touser=o2IGD0a1OvYAEBfPRa8t34Wc2nUo&msgtype=text&text[content]=123'

3. Uploading Multimedia Files

When the UDESK system uploads multimedia files, the simulated middleware requests the WeChat server's "Add Temporary Material" interface and passes the return from the WeChat server to the UDESK system.

The method of the simulated middleware uploading files to the WeChat server, see WeChat Developer Documentation - Material Management - Add Temporary Material

Initiator	Receiver	Request Method
UDESK System	Simulated Middleware	POST

Request Description

POST 'Customer filled in simulated domain name address?type=TYPE'

Request Parameters

Parameter	Description
type	File type, image/voice/video
media	Value is file stream

Return Value

See the return value of WeChat Developer Documentation - Material Management - Add Temporary Material

Example

# Example of calling (using curl command to upload a multimedia file with FORM)
# Content-Type: multipart/form-data
curl -F media=@test.jpg "www.simulate_weixin.com?type=TYPE"

4. Getting Multimedia Files

When the UDESK system gets multimedia files, the simulated middleware requests the WeChat server's "Get Temporary Material" interface and passes the return from the WeChat server to the UDESK system.

The method of the simulated middleware requesting files from the WeChat server, see WeChat Developer Documentation - Material Management - Get Temporary Material

Initiator	Receiver	Request Method
UDESK System	Simulated Middleware	GET

Request Description

GET 'Customer filled in simulated domain name address?media_id=MEDIA_ID&access_token=ACCESS_TOKEN'

Request Parameters

Parameter	Description
access_token	Virtual access_token
media_id	Media file ID in WeChat server

Return Value

See the return value of WeChat Developer Documentation - Material Management - Get Temporary Material

Example

# Example of calling
curl www.simulate_weixin.com?media_id=abc&access_token=123

Note

Why does the UDESK system need to upload and get multimedia files?

When sending and receiving messages, operations such as obtaining and calling multimedia messages such as images and voice are performed through the media_id inside WeChat.  
When sending images, voice, and other messages, you need to upload the file content to the WeChat server to obtain the media_id.  
When receiving images, voice, and other messages, you need to obtain the actual file content from the WeChat server.

5. Get Customer Avatar and Nickname

When the UDESK system needs to get customer avatar and nickname, the UDESK system requests the simulated middleware. The simulated middleware then requests the WeChat server's "Get User Basic Information" interface and passes the return from the WeChat server to the UDESK system.

For the method of the simulated middleware requesting customer basic information from the WeChat server, see WeChat Developer Documentation - User Management - Get User Basic Information (UnionID Mechanism)

Initiator	Receiver	Request Method
UDESK System	Simulated Middleware	GET

Request Description

GET 'Customer filled simulated domain name address?openid=OPEN_ID&lang=zh_CN'

Request Parameters

Parameter	Description
openid	Customer's openid
lang	Returns the language version of the country/region. Currently, only supports zh_CN (Simplified Chinese)

Return Value

The simulated middleware passes the information returned from the WeChat server to the UDESK system.

See WeChat Developer Documentation - User Management - Get User Basic Information (UnionID Mechanism) for details.

Example

# Request example
curl 'www.simulate_weixin.com?openid=o-NbF1HPuegFK5sa1psr7EEeSTSg&lang=zh_CN'

Note

UDESK system will remove special characters from the nickname.

6. Get Template Messages

When the UDESK system needs to get template messages, it requests the simulated middleware. The simulated middleware then requests the WeChat server's "Get Template List" interface and passes the return from the WeChat server to the UDESK system.

For the method of the simulated middleware getting template messages from the WeChat server, see WeChat Developer Documentation - Message Management - Get Template List

Initiator	Receiver	Request Method
UDESK System	Simulated Middleware	GET

Request Description

GET 'Customer filled simulated domain name address/template/get_all_private_template'

Request Parameters

None

Return Value

The simulated middleware passes the information returned from the WeChat server to the UDESK system.

See WeChat Developer Documentation - Message Management - Get Template List for details.

Example

# Request example
curl 'www.simulate_weixin.com/template/get_all_private_template'

# Response example
{
  "template_list": [
    {
      "template_id": "iPk5sOIt5X_flOVKn5GrTFpncEYTojx6ddbt8WYoV5s",
      "title": "Reward Collection Reminder",
      "primary_industry": "IT Technology",
      "deputy_industry": "Internet|E-commerce",
      "content": "{ {result.DATA} }\n\nReward Amount:{ {withdrawMoney.DATA} }\nReward Time:{ {withdrawTime.DATA} }\nBank Info:{ {cardInfo.DATA} }\nArrival Time:{ {arrivedTime.DATA} }\n{ {remark.DATA} }",
      "example": "You have submitted a reward application\n\nReward Amount: xxxx yuan\nReward Time: 2013-10-10 12:22:22\nBank Info: xx bank (ending in xxxx)\nArrival Time: estimated xxxx\n\nExpected to arrive at your bank on xxxx"
    }
  ]
}

7. Send Template Messages

When the UDESK system needs to send template messages, it requests the simulated middleware. The simulated middleware then requests the WeChat server's "Send Template List" interface and passes the return from the WeChat server to the UDESK system.

For the method of the simulated middleware sending template messages to the WeChat server, see WeChat Developer Documentation - Message Management - Send Template List

Initiator	Receiver	Request Method
UDESK System	Simulated Middleware	POST

Request Description

POST 'Customer filled simulated domain name address/message/template/send'

Request Parameters

See WeChat Developer Documentation - Message Management - Send Template List for details.

{
  "touser": "OPENID",
  "template_id": "ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
  "url": "http://weixin.qq.com/download",
  "miniprogram": {
    "appid": "xiaochengxuappid12345",
    "pagepath": "index?foo=bar"
  },
  "data": {
    "first": {
      "value": "Congratulations on your successful purchase!",
      "color": "#173177"
    },
    "keyword1": {
      "value": "Chocolate",
      "color": "#173177"
    },
    "keyword2": {
      "value": "39.8 yuan",
      "color": "#173177"
    },
    "keyword3": {
      "value": "September 22, 2014",
      "color": "#173177"
    },
    "remark": {
      "value": "Welcome to buy again!",
      "color": "#173177"
    }
  }
}

Return Value

The simulated middleware passes the information returned from the WeChat server to the UDESK system.

See WeChat Developer Documentation - Message Management - Send Template List for details.

{
  "errcode":0,
  "errmsg":"ok",
  "msgid":200228332
}

Example

# Request example
curl 'www.simulate_weixin.com/message/template/get_all_private_template' -d '
  {
    "touser": "OPENID",
    "template_id": "ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
    "url": "http://weixin.qq.com/download",
    "miniprogram": {
      "appid": "xiaochengxuappid12345",
      "pagepath": "index?foo=bar"
    },
    "data": {
      "first": {
        "value": "Congratulations on your successful purchase!",
        "color": "#173177"
      },
      "keyword1": {
        "value": "Chocolate",
        "

color": "#173177"
      },
      "keyword2": {
        "value": "39.8 yuan",
        "color": "#173177"
      },
      "keyword3": {
        "value": "September 22, 2014",
        "color": "#173177"
      },
      "remark": {
        "value": "Welcome to buy again!",
        "color": "#173177"
      }
    }
  }'

# Response example
{
  "errcode":0,
  "errmsg":"ok",
  "msgid":200228332
}

8. Access_token Retrieval

The UDESK system does not interact directly with the WeChat server, so there is no need for an access_token.

For the simulated middleware to obtain access_token from WeChat, see WeChat Developer Documentation - Getting Started - Getting Access token

Basic Information

1. Receiving Messages

Request Description

Request Parameters

Return Value

Example

2. Pushing Messages

Request Description

Request Parameters

Return Value

Example

3. Uploading Multimedia Files

Request Description

Request Parameters

Return Value

Example

4. Getting Multimedia Files

Request Description

Request Parameters

Return Value

Example

Note

5. Get Customer Avatar and Nickname

Request Description

Request Parameters

Return Value

Example

6. Get Template Messages

Request Description

Request Parameters

Return Value

Example

7. Send Template Messages

Request Description

Request Parameters

Return Value

Example

8. Access_token Retrieval

Products

Solutions

Resources