wxpusher docs
1.0.0
WxPusher (WeChat push service) is a real-time information push platform that uses WeChat public accounts as channels. You can push information to WeChat by calling APIs without installing additional software to achieve real-time notification of information. You can use WxPusher to make server alarm notifications, class rush notifications, ticket rush notifications, information update prompts, etc.
You can access the demo program and experience the functionality: https://wxpusher.zjiecode.com/demo/
Demo program source code: https://github.com/wxpusher/wxpusher-sdk-java/
Management background: https://wxpusher.zjiecode.com/admin/
Please be sure not to call the demo program and send messages directly to users! ! !
The WeChat interface has been adjusted. The method of sending text messages directly has been offline . We are developing new push methods, so stay tuned.
| type | Get user ID | template message | |||
|---|---|---|---|---|---|
| Preview |  |  |  |  |  |
In order to facilitate different user groups and different usage scenarios to send messages more quickly and conveniently, we currently support 2 ways of using WxPusher.
- Please note that these two sending methods have different identity marks and cannot be migrated or switched between each other;
- If possible, it is strongly recommended to use the first method for better capabilities.
| Send method | Advantages, disadvantages and applicable scenarios |
|---|---|
| Standard push [recommended] (Standard application development) |
|
| Minimalist push (SPT one-click push) |
|
Corresponding to one of your projects, it is mainly used for authentication, resource isolation, etc. (similar to using Amap SDK, WeChat login, etc., you will first create a new application). Each application has an independent name, QR code, and callback address. The first step to call resources, authentication information, etc. and send messages is to create a new application.
To understand simply, you have a project to grab train tickets. Once you grab the tickets, you need to send a message to the user; you also have a project to alert the server. When the server is abnormal, send a message to the relevant person in charge. What are the uses of these two? are different, you can create 2 applications to send their information separately.
Users can follow this application through the QR code or link. By following, we will call back the user's UID to your designated server. You can send information to this user through the UID.
Topic is a collection of messages under the application. For example, a discount-related application is created to push various preferential information to users. However, different users pay attention to different preferential information. Some people pay attention to Taobao, and some people pay attention to Taobao. People pay attention to JD.com. In this scenario, you can create a Taobao topic, and then create a JD.com topic. When sending information, just send it directly to the corresponding topic. Each topic has a corresponding subscription link and QR code. Users After subscribing to this topic, you can receive information under this topic.
Topics can only be sent to groups indiscriminately, and messages cannot be customized for users. After users follow them, there will be no callback information.
| project | application | Topic |
|---|---|---|
| concept | The application is an independent entity | The theme belongs to the application, and calling the theme requires the APP_TOKEN authorization of the corresponding application. |
| How to follow | QR code and link | QR code and link |
| Send group | Send one-to-one by UID | After the message is sent to the topic, the topic is then distributed to users who follow the topic, which is a group message. |
| project | Apply QR code | Theme QR code |
|---|---|---|
| use | Used for WeChat users to follow applications. Users only follow your application. Only then can you get his UID and send him messages. | Used to subscribe to topics. After a user subscribes to a topic, you cannot get its UID. |
| Dynamic and static | Default dynamic QR code | Default dynamic QR code |
Dynamic QR code : The QR code link will not change, but the QR code graphic will change, so only dynamic QR code links can be used, and screenshots, printing, etc. are not allowed.
Static QR code : The QR code links and graphics remain unchanged and can be used at will.
The identity token of the application can only be known to you as the developer. With APP_TOKEN, you can send messages to users of the corresponding application, so please keep it strictly confidential and do not send it to places like github.
The WeChat user logo is used to indicate which user the message should be sent to when sending a message to a user alone.
Before accessing, you can look at the architecture diagram to help you understand the difference between single transmission and group transmission. 
https://wxpusher.zjiecode.com/admin/, use WeChat to scan the QR code to log in, no registration is required, and new users will be automatically registered by scanning the QR code for the first time.
Create an application as shown below:
Callback address: You don’t have to fill it in. If you don’t fill it in, there will be no callback when the user follows it. You can’t get the user’s UID. Please refer to the callback description.
Set URL: You don’t need to fill it in. After filling it in, the user can open “My Subscription” on WeChat and jump directly to this address, and the uid will be carried as a parameter to facilitate customized page display.
Contact information: You don’t need to fill it in. Tell the user how to contact you and give you feedback.
Follow prompt: A prompt sent to the user when the user follows or scans the application code. You don’t need to fill it in. Wxpusher will provide a default copy. You can also actively push a reminder message to the user when the user pays attention to the callback and gives you the UID.
Description: Describe your application and what content it pushes. Users can see it when they follow the link or view it on WeChat.
During the process of creating your application, you should have seen the appToken. If it is not saved, you can reproduce it in the following way.
Open the backend of the application https://wxpusher.zjiecode.com/admin/, and find the appToken menu from the left menu bar. Here, you can reset the appToken. Please note that after reset, the old appToken will become invalid immediately. Calling the interface will fail.
After creating an application, you can see the application code and follow link of the application. You can let your users follow your application in the following two ways. After following your application, you can send him messages.
There are currently 3 ways to obtain UID:
After getting the UID, match the appToken of the application, and then call the sending interface to send the message.
All interfaces already support https.
POST interface The POST interface is a fully functional interface and is recommended for use.
Content-Type:application/json
Address: https://wxpusher.zjiecode.com/api/send/message
The request data is placed in the body, and the specific parameters are as follows:
JSON does not support comments. When sending, comments need to be deleted.
{
"appToken" : " AT_xxx " , //必传
"content" : " <h1>H1标题</h1><br/><p style= " color:red; " >欢迎你使用WxPusher，推荐使用HTML发送</p> " , //必传
//消息摘要，显示在微信聊天页面或者模版消息卡片上，限制长度20(微信只能显示20)，可以不传，不传默认截取content前面的内容。
"summary" : "消息摘要" ,
//内容类型 1表示文字 2表示html(只发送body标签内部的数据即可，不包括body标签，推荐使用这种) 3表示markdown
"contentType" : 2 ,
//发送目标的topicId，是一个数组！！！，也就是群发，使用uids单发的时候， 可以不传。
"topicIds" :[
123
],
//发送目标的UID，是一个数组。注意uids和topicIds可以同时填写，也可以只填写一个。
"uids" :[
" UID_xxxx "
],
//原文链接，可选参数
"url" : " https://wxpusher.zjiecode.com " ,
//是否验证订阅时间，true表示只推送给付费订阅用户，false表示推送的时候，不验证付费，不验证用户订阅到期时间，用户订阅过期了，也能收到。
//verifyPay字段即将被废弃，请使用verifyPayType字段，传verifyPayType会忽略verifyPay
"verifyPay" : false ,
//是否验证订阅时间，0：不验证，1:只发送给付费的用户，2:只发送给未订阅或者订阅过期的用户
"verifyPayType" : 0 }
html格式的消息（contentType=2），支持通过标签复制，复制的语法如下：
```html
<copy style="这里可以写复制按钮的style" data-clipboard-text="需要复制到剪贴板的内容">
复制按钮的文字
</copy>
一个例子如下，style默认可以不写：
<copy data-clipboard-text="被复制的内容">
复制
</copy>
Return data description:
{
"code" : 1000 , //状态码，非1000表示有异常
"msg" : "处理成功" , //提示消息
"data" : [ //每个uid/topicid的发送状态，和发送的时候，一一对应，是一个数组，可能有多个
{
"uid" : " UID_xxx " , //用户uid
"topicId" : null , //主题ID
"messageId" : 121 , //废弃️，请不要再使用，后续会删除这个字段
"messageContentId" : 2123 , //消息内容id，调用一次接口，生成一个，你可以通过此id调用删除消息接口，删除消息。本次发送的所有用户共享此消息内容。
"sendRecordId" : 12313 , //消息发送id，每个uid用户或者topicId生成一个，可以通过这个id查询对某个用户的发送状态
"code" : 1000 , //1000表示发送成功
"status" : "创建发送任务成功"
}
],
"success" : true
}
GET interface The GET interface is a castration of the POST interface. It is mainly for the convenience of calling in some cases. It only supports sending text (contentType=1). For example:
https://wxpusher.zjiecode.com/api/send/message/?appToken=AT_qHT0cTQfLwYOlBV9cJj9zDSyEmspsmyM&content=123&uid=c1BcpqxEbD8irqlGUh9BhOqR2BvH8yWZ&url=http%3a%2f%2fwxpusher.zjiecode.com
Request parameters support: appToken, uid , topicId , content, url, verifyPayType. Please perform urlEncode encoding on content and url.
The GET interface only supports sending a uid or topicId. It is recommended to use the POST interface.
The message is sent to Wxpusher, which will be cached, pushed asynchronously to WeChat in the background and then distributed to users. When the number of messages is huge, there may be a delay. You can query the sending status of the message to this user based on the sendRecordId returned by sending the message.
Request method: GET
Note: Query the message status. The message cache is time-sensitive. The cache time is currently set to 7 days. If you query the message after 7 days, it may return that the message does not exist.
Request address: https://wxpusher.zjiecode.com/api/send/query/status?sendRecordId={sendRecordId}
Parameter description:
Request method: DELETE
Note: After the message is sent, you can call the secondary interface to delete the message. However, please note that only the landing page that the user clicked to view the details can be deleted. Message records that have been pushed to the user cannot be deleted.
Request address: https://wxpusher.zjiecode.com/api/send/message?messageContentId=${messageContentId}&appToken=${appToken}
Parameter description:
There is a scenario where you need to know who scanned the QR code. For example, there are new messages in forum posts that need to be pushed to users. If the user scans the code to follow, you need to know who scanned the QR code and put the forum user ID. Bind to the UID of the Wxpusher user. When there is a new message from the forum user ID, it will be pushed to the Wxpusher user. This scenario requires a QR code with parameters.
Request method: POST
Request address: https://wxpusher.zjiecode.com/api/fun/create/qrcode
ContentType: application/json
Description: Create a QR code with parameters. After the user scans the code, the parameters will be included in the callback. Please refer to the callback description.
Request body:
{
"appToken" : " xxx " , //必填，appToken,前面有说明，应用的标志
"extra" : " xxx " , //必填，二维码携带的参数，最长64位
"validTime" : 1800 //可选，二维码的有效期，默认30分钟，最长30天，单位是秒
}
After the user scans the parameter QR code and sets the callback address, we will push the user's UID to your service through the callback address. For details, see the callback description. It is recommended to use this callback method.
However, some user scenarios are simple, or there is no back-end service, such as client software, which is very inconvenient to use. Therefore, we have added this query interface. Create a QR code through the above creation parameter QR code interface, and you will get A QR code code. Use this code with this interface to query the UID of the user who last scanned the parameter QR code.
The training interval cannot be less than 10 seconds! ! Infinite loop training is prohibited. After the user exits, the training must be turned off, otherwise the account will be banned.
Request method: GET
Request address: https://wxpusher.zjiecode.com/api/fun/scan-qrcode-uid
Request parameters (Query):
an example
https://wxpusher.zjiecode.com/api/fun/scan-qrcode-uid?code=xxxxx
This interface has been deprecated. Please use the following user V2 interface to query the App. You can use this interface to query all WeChat users who follow your App by page.
Request method: GET
Description: Obtain the user information of all WeChat users who follow the application
Request address: https://wxpusher.zjiecode.com/api/fun/wxuser
Request parameters:
Return data:
{
"page" : 1 , //当前数据页码
"pageSize" : 50 , //当前页码大小
"records" :[
{
"createTime" : 1572755754416 , //用户关注时间
"enable" : true , //是否可用，也就是用户是否开启接收消息
"headImg" : " xxxxxx " , //用户头像
"nickName" : " 0XFF " , //用户昵称
"uid" : " xxxxxxx " //用户的UID
}
],
"total" : 3 //所有的用户数量
}You can use this interface to query all users who follow the application and topics by page.
Request method: GET
Description: Obtain the user information of all WeChat users who follow the application/topic. It should be noted that if a WeChat user follows applications, topics, or even multiple topics at the same time, multiple records will be returned.
Request address: https://wxpusher.zjiecode.com/api/fun/wxuser/v2
Request parameters:
{
"code" : 1000 ,
"msg" : "处理成功" ,
"data" : {
"total" : 40 , //总数
"page" : 1 , //当前页码
"pageSize" : 20 , //页码大小，
"records" : [
{
"uid" : " UID_xxx " , //用户uid
"appOrTopicId" : 111 , //用户关注的应用或者主题id，根据type来区分
"headImg" : " " , //新用户微信不再返回 ，强制返回空
"createTime" : 1603540859285 , //创建时间
"nickName" : " " , //新用户微信不再返回 ，强制返回空
"reject" : false , //是否拉黑
"id" : 47361 , //id，如果调用删除或者拉黑接口，需要这个id
"type" : 0 , //关注类型，0：关注应用，1：关注topic
"target" : " WxPusher官方" , //关注的应用或者主题名字
"payEndTime" : 0 // 0表示用户不是付费用户，大于0表示用户付费订阅到期时间，毫秒级时间戳
}
]
},
"success" : true
}You can delete users' attention to applications and topics through this interface.
Request method: DELETE
Note: You can delete the user's attention to the application or topic. After deletion, the user can follow it again. If you do not want the user to follow it again, you can call the block interface to block the user.
Request address: https://wxpusher.zjiecode.com/api/fun/remove
Request parameters (Query):
Return data:
{
"code" : 1000 ,
"msg" : "处理成功" ,
"data" : "删除成功" ,
"success" : true
}You can use this interface to block users
Request method: PUT
Note: No more messages can be sent after being blocked, and the user cannot follow him again unless you unblock him. Call the blacklist interface instead of calling the delete interface.
Request address: https://wxpusher.zjiecode.com/api/fun/reject
Request parameters (Query):
Return data:
{
"code" : 1000 ,
"msg" : "处理成功" ,
"data" : "删除成功" ,
"success" : true
}In order to facilitate quick access, enthusiastic developers have contributed many access SDKs, https://github.com/wxpusher/wxpusher-client.
The SDK is contributed by developers and may not include the latest API or functions. The functions are subject to the HTTP interface in this article. You are also welcome to submit PR to us.
Minimalist push, no need to register a user, log in to the backend, create an application, obtain appToken, etc.
In order to prevent users from understanding too many concepts and making access difficult, in some scenarios where users send messages to themselves , a minimalist push method can be used.
For example: some open source shopping mall order systems send messages to users after placing orders; SMS forwarding systems, etc.; previously, users were required to create applications, obtain appTokens, follow applications, fill in UIDs, etc. For ordinary users, the cost was too high.
Minimalist push only requires 2 steps to complete the push:
Simply scan the QR code below to get your push SPT
If you need to display this QR code in your system, you can use the following permanent link:
<textarea readonly style="width:100%;height:60px;"> https://wxpusher.zjiecode.com/api/qrcode/RwjGLMOPTYp35zSYQr0HxbCPrV9eU0wKVBXU1D5VVtya0cQXEJWPjqBdW3gKLifS.jpg </textarea>Please do not leak SPT. After SPT is leaked, any user can send you messages! ! !
Simple sending of GET request
Put the SPT you obtained in the previous step in the link below
Direct request: https://wxpusher.zjiecode.com/api/send/message/The SPT you obtained/the content you want to send
Simple sending of POST requests
Request method: POST
Request URL: https://wxpusher.zjiecode.com/api/send/message/simple-push
Request format: Content-Type:application/json
Request content:
//JSON不支持注释，发送的时候，需要删除注释。
{
//推送内容，必传
"content" : " <h1>极简推送</h1><br/><p style= " color:red; " >欢迎你使用WxPusher，推荐使用HTML发送</p> " ,
//消息摘要，显示在微信聊天页面或者模版消息卡片上，限制长度20(微信只能显示20)，可以不传，不传默认截取content前面的内容。
"summary" : "消息摘要" ,
//内容类型 1表示文字 2表示html(只发送body标签内部的数据即可，不包括body标签，推荐使用这种) 3表示markdown
"contentType" : 2 ,
//发送SPT，如果发送给一个用户，直接传simplePushToken就行了，不用传simplePushTokenList
"spt" : " SPT_xx1 " ,
//发送SPT，如果发送给多个用户，只传simplePushTokenList即可，请注意，【这是一个数组】！！，最多不能超过10个
"sptList" :[ " SPT_xx1 " , " SPT_xx2 " ],
//原文链接，可选参数
"url" : " https://wxpusher.zjiecode.com " ,
}
Please note: Only method one (standard push) supports callbacks
When a user follows an application or sends a command message to an official account, WxPusher will push the message to you. If you do not have a background service, you can also perform rotation training. Please refer to the query scan QR code user UID interface.
To send a message to a user, you need to know the user's UID. There are two ways to know the user's UID:
{
"action" : " app_subscribe " , //动作，app_subscribe 表示用户关注应用回调，后期可能会添加其他动作，请做好兼容。
"data" :{
"appId" : 123 , //创建的应用ID
"appKey" : " AK_xxxxxx " , //关注应用的appKey，请不要再使用，将来可能会被删除
"appName" : "应用名字" ,
"source" : " scan " , //用户关注渠道，scan表示扫码关注，link表示链接关注，command表示通过消息关注应用，后期可能还会添加其他渠道。
"userName" : " " , //新用户微信不再返回 ，强制返回空
"userHeadImg" : " " , //新用户微信不再返回 ，强制返回空
"time" : 1569416451573 , //消息发生时间
"uid" : " UID_xxxxxx " , //用户uid
"extra" : " xxx " //用户扫描带参数的二维码，二维码携带的参数。扫描默认二维码为空
}
}For messaging products, developers may need to be aware of the user's paid subscription status after the user has paid or refunded.
Therefore, when the user's paid subscription status changes, you will be notified through the following callback message. When you receive the notification, you can query the user's subscription expiration time and other information by querying the user list V2.
{
"action" : " order_pay " , //动作，表示用户付费或者退款。后期可能会添加其他动作，请做好兼容。
"data" :{
"addTime" : 86400000 , //付费增加的时间，毫秒。退款是负数，表示减少的订阅时间。
"amount" : 50 , //金额，单位分，退款是负数
"appId" : 30630 , //发生的应用id
"createTime" : 1664118481675 , //发生时间，毫秒级时间戳
"prodId" : 12 , //产品id
"tradeNo" : " 202209252308016755383125546 " , //支付或者退款的交易号，和用户微信账单中的商户号对应
"type" : 1 , //1表示付款，2表示退款
"uid" : " UID_xxxxxxx " //发生用户的uid
}
}At present, WxPusher already supports upstream messages of the command type. When the user sends a command, WxPusher will call back the command message to the developer.
standard directive
The format of the command is: #{appID} content . For example, to send a message to the demo program, you can send: #97 test. Note that there is a space in the middle.
Subscription instructions
If you only send appID: #{appID} , for example: #97, and there is no content after it, it means you are paying attention to the application with appID 97.
Simplified instructions
If you only send content: xxx, for example: restart the server, this time is divided into two situations:
The appID can be viewed in the management background, application management-application information-application id.
The callback uses the POST method, and the data format is as follows:
{
"action" : " send_up_cmd " , //动作，send_up_cmd 表示上行消息回调，后期可能会添加其他动作，请做好兼容。
"data" :{
"uid" : " UID_xxx " , //用户uid
"appId" : 97 , //应用id
"appName" : " WxPusher演示" , //应用名称
"time" : 1603002697386 , //发生时间
"content" : "内容" //用户发送的内容
}
}Please note: Only method one (standard push) supports message product charging
Please note that this charge refers to: message developers charging message receivers through WxPusher, not WxPusher charging developers or users.
As a developer, you are responsible for providing valuable information, and we are responsible for helping you make money.
The access process is as follows:
Message products are packages of single-sent application messages and group-sent topic messages. Multiple messages can be packaged into one message product for sale.
Please note that we currently do not accept strategy recommendation news on stocks, options, bonds, funds, etc.
You need to pay attention to a concept. What we sell are product-bound resources. For example, if the resources are generally sent in bulk, they will be bound to the theme; if they are sent one-to-one through uid, they will be bound to the application.
Please note that the current product does not support modification after it is created. Please fill it out clearly before submitting.
After submission, please contact the customer service WeChat "wxpusher-kefu" for review and negotiation on payment price strategy. After completion, it can be put on the message market, and users can pay and purchase directly in the message market.
| illustrate | news market | Messaging product list | Message product introduction |
|---|---|---|---|
| Example |  |  |  |
User information can be queried by querying the user list V2, where payEndTime is the user's subscription expiration time.
When sending a message to an application or theme packaged as a product, you can distinguish whether this message can only be received by users within the paid subscription period. Make a distinction based on the verifyPayType field
For details, you can check the interface description for sending messages. If there is no application or topic associated with the message product, the verifyPayType field is invalid and does not need to be passed.
You need to pay attention to a concept. We sell resources bound to products, so what we query is the expiration time corresponding to the resource. For example, if the message is generally sent in bulk, it is bound to the topic; if the message is sent one-to-one through uid, it is bound to the application, and the query is the expiration time of the subscription topic or application.
Request method: GET
Description: The expiration time of a certain user on a certain resource. Because a product can be bound to multiple resources, an array is returned (but generally multiple resources are not bound).
Request address: https://wxpusher.zjiecode.com/api/product/query-pay-end-time?uid={uid}&prodId={product id}
Parameter description:
Response parameters:
{
"code": 1000,
"msg": "处理成功",
"data": [
{
"resourceType": 2, //资源类型，1对1uid发送的应用为1，群发主题为2
"resourceID": 123, //应用id或者主题id
"payEndTime": 1737560859272 //用户付费订阅到期时间，毫秒级的时间戳
}
],
"success": true
}
If yours is a software product, please access WxPusher's authorization, so that users can easily bind it to the corresponding expiration time after purchase. The general verification process is:
For a better user experience, we are working hard to develop more clients to improve the user experience.
The Chrome extension is an extension based on the Chrome browser. As long as the browser is open, you can receive messages. It currently supports Mac and Windows computers. The experience of receiving messages is better than WeChat. Welcome to try it. You can visit here https://github.com/wxpusher/wxpusher-chrome-extensions to download and install the browser extension.
You can also visit here to view the specific installation and usage methods: https://mp.weixin.qq.com/s/zrUdVqrE0odhUTiD7qhWiQ
Because it is currently developed based on the browser V2 API, Google will not allow it to be put on the shelves. We will put it on the Chrome Store after we migrate to V3.
Due to the content restrictions of WeChat, for a better user experience, you are welcome to download the iOS Apple client to receive messages for a better user experience. The download method is as follows:
Due to domestic Android ecological issues, Android applications are still under development. We are very sorry.
WxPusher is a free push service. In order to better serve everyone, here are the system-related data restrictions.
