Template message

This kind of message allows users of your chat channel to communicate with your system, or any other system, that can handle requests.

There are two ways a user can make a request, as follows:

1. Without any additional input from the user: when the user wants to get information about all his papers
2. With an additional input from the user: user want to get info about specific paper and need to enter paper ID

For all below listed cases related to the Template message, let's assume that WeChat Gateway will send a request to the http://example.com/my/path and current WeChat channel user ID is myuserid.

1. Case without an additional input

It means that WeChat Gateway will send the following request:

HTTP GET http://example.com/my/path?wechat_id=myuserid

wechat_id - ID of WeChat channel user, that is trying to make a request.

2. Case with an additional input from user

Same as above, except that it will send the additional parameter input.

Let's assume that for the question 'What is paper ID?' the user inputs the following text: '123456'

The system will make the following request:

HTTP GET http://example.com/my/path?wechat_id=myuserid&input=123456

For these two cases, your system should response in one way

Response code is always HTTP 200 OK and a response body has the following template:

{
  "error": ..,
  "result": ..
}

error field is for warning/error messages for user and this is the way to trigger user authorization.

The error field must have the following structure:

{
  "error": {
    "message": "Some message for user",
    "code": 403 // not required
  }
}

If the response body contains a field error then system will act in a following way:

• if error contains a code field and its value equals to 403(Forbidden) then system will send an auth pop-up to the user. Other error codes are ignored.
• if error contains a field message then the system will send a message field text to the user,

for example, for the request to get user paper info by ID:

if the user enters an invalid ID (or the paper ID does not belong to the user) then system can response in a following way:

{
  "error": {
    "message": "Sorry this paper doesn't belong to you\Please try once more"
  }
}

The user will see the above message.

• If none of the above cases can be processed then system will send a warning message to the user that external(yours) system responses with an invalid body.

For a successful request the system will response in a following way:

{
  "error": null,
  "result": {
     "paper_name": "My great paper",
     "some_other_field": ""
  }
}

The type of result can be either object or array. The result contains all required information to render the template message to the user.

Notification API

 

After you register your company on WeChat Gateway, the system allocates a domain for you. You can find this domain at https://cwbot.com.cn/company/details. Let's assume that the system allocates domain 2000.cwbot.com.cn, then your system needs to make HTTP POST request to the following URL: https://2000.cwbot.com.cn/api/v1/notification/push

This is secured resource, so you will need to provide auth credentials. The system supports a modified Basic Auth type. Typical Basic Auth is base64(username:password), but our system support the following Basic Auth type: base64(username:MD5(password)).

username & password - these is the credentials of any user that belongs to your company with the admin role. list of company users can be found here: https://cwbot.com.cn/company/users

The request body should have the following structure:

{
  "wechat_id": "..the id of user, who must get notification..",
  "message_alias": "alias of template message",
  "body": { }
}

body can be either object or array. The system will pass it based on how you create template message (response type parameter).

The system will response to you in a following way:

{
  "error": {
    "code": ..,
    "message": ..
  },
  "result": ..
}

if error field is in response then this means that your system sends invalid request. message will describe problem, while code fields can have following values

• 403 - you passed invalid auth credentials or user with following credentials doesn't have permission to access this resource
• 401 - invalid auth type. In case if you did not send Authentication header or this header doesn't have valid Basic Auth value
• 400 - multiple cases: invalid domain, not all parameters are present
• 404 - multiple cases: not existed a message alias

If your system sends a valid request, then the WeChat Gateway will response with the following body:

{
  "result": true/false
}

true - if everything is OK and WeChat Gateway managed to send the notification to the user.

false - is everything is OK(with your request), but WeChat can not send the notification to the user(for example if you have exhausted your daily limit for WeChat notifications).