wxpusher-sdk-java pushes WeChat messages over a small REST surface

What the SDK actually covers

WxPusher is a service for pushing messages to personal WeChat accounts in real time over an API, and this repository is the Java client for it. The scope is small and well defined, which is the main argument for using it. The client exposes sending a message, deleting a message, creating an app temporary QR code, querying the UID of a user who scanned one, querying user records, deleting a user subscription and blacklisting a user. Underneath, the calls return a Result wrapper with an isSuccess flag, a message string and a typed data field, and the data type varies by call, from a list of per-recipient results for sending, to a Page of user records for the user query, to a plain Boolean for the delete and blacklist operations. The project is a single Gradle module layout with client-sdk/ holding the library and demo/ holding the sample that backs the online demo site.

Adding the dependency, and the version mismatch in the docs

The SDK is published under the groupId com.smjcco.wxpusher with the artifactId client-sdk, and the README gives both a Gradle and a Maven form. The Maven form is the cleaner of the two.

<dependency>
  <groupId>com.smjcco.wxpusher</groupId>
  <artifactId>client-sdk</artifactId>
  <version>3.0.2</version>
</dependency>

The Gradle form needs the JCenter repository configured in the build file, which is worth noticing on its own, since JCenter has been read-only for some time and a build that relies on it is a build with a dependency on an artifact host that no longer serves new releases. There is also a version inconsistency inside the documentation itself, since the Gradle example names 3.0.0 while the Maven example and the version badge both say 3.0.2. If you take the Gradle line verbatim you will get an older patch release than the one the rest of the page points at, which is a small thing to check before you spend an afternoon wondering why a method is missing. The release history shows v3.0.2 published on 2025-04-13 and 2.1.4 from 2020-06-26, so the current line and the old line are years apart.

One instance for most apps, several when you need them

The client has two construction patterns, and choosing between them is the first decision a user makes. If you need a single instance, which means a single appToken, you initialise a default client once and use it everywhere afterwards.

Message message = new Message();
message.setContentType(Message.CONTENT_TYPE_TEXT);
message.setUid("UID_XXXX");

Result<List<MessageResult>> result = WxPusher.getDefaultWxPusher().send(message);
if (result.isSuccess() && result.getData() != null) {
  for (MessageResult messageResult : result.getData()) {

The alternative is to instantiate the client yourself with your own appToken and keep the reference, which is what the documentation suggests when you need several instances at once, for example one per application in a multi-tenant service. The send call takes a Message with a content type and a target, and a target can be a user UID or a topic, and when you pass several of them the result carries one entry per recipient, which is why the data field is a list rather than a single object. The content type is set through a constant on the Message class, with the text type shown in the example, and the response exposes each recipient's UID and status so a partial failure is visible rather than silent.

QR codes, callbacks and the two ways to learn a user's UID

The interesting part of the API is the app temporary QR code, and it comes with a documented alternative that the README actually recommends. The create call takes a request object with an extra data field for your own payload and a valid time in seconds, with the example setting 1800 for a validity of 30 minutes, and it returns a code, a URL, a short URL, an expiry and the extra data you supplied. The purpose is to tie a scanning user to a user in your own system. There are two ways to close the loop, and the documentation is clear about the preference. You can poll queryScanUID with the code, but the example carries a comment noting that the polling interval must not be less than 10 seconds and that this is only an example, and the README says the callback approach is preferred. The callback route is a webhook, and the data models for it are already defined in the SDK under the com.smjcco.wxpusher.sdk.bean.callback package, with the demo module showing how to handle them. The one action that cannot be undone is deleting a message, and the documentation is explicit that the delete call removes only the landing page a user would open, not the pushed message record itself.

User management, blacklisting and the second API surface

The user query returns a Page of user records, and the fields it exposes are the ones you need to manage a follower list, with the total, the page number, the page size, and per user the UID, the ID, the application or topic ID, the subscription type, an enabled flag, a blacklisted flag and the creation time. The README notes that the same user following several applications can produce several records, so the query result is not necessarily one row per person. The call takes a page number, a size, a third argument that is null in the example, a boolean, and a UserType, with UserType.APP used to scope it to application subscriptions rather than topic subscriptions. Deleting a user removes the subscription and the user can follow again, whereas blacklisting prevents further messages and prevents the user from following again unless the blacklist is lifted, and the documentation notes that you do not need to call the delete first, since the blacklist call alone is enough. That pair of methods is the practical difference between a user leaving and a user being excluded, and it is the one piece of state a sending service cannot infer for itself.

Where the SDK is the wrong choice

Three limits, and they are mostly about dependency hygiene. The first is that a handful of REST calls does not need a client library, and the project says so itself, noting that if no SDK exists for your language you can call the HTTP interface directly using the reference documentation, and welcoming contributions of SDKs in other languages. The Go and Python SDKs exist for the same reason, which tells you the surface area is small enough that a raw HTTP call is a reasonable alternative. The second is the JCenter dependency in the Gradle instructions, which as noted is a repository that no longer accepts new artifacts, so following the Gradle example literally in a new project is likely to fail to resolve. The third is the 3.x break. The README leads with a notice that upgrading to 3.x brought many breaking changes, that the changes are not large in practice, and that the 2.x version lives on the version_2.x branch. That is a fair warning rather than a serious problem, but it means the version you pick decides how much of your integration code you rewrite, and the project does not document the individual breaking changes in the readme itself, so the diff between branches is the only reference available there. The licence is Apache 2.0, and the last push to the repository was on 2026-06-15.

Editorial conclusion

Adopt wxpusher-sdk-java if you are sending WeChat push messages from a Java service and you want typed models for the responses rather than hand written HTTP calls, since the whole API surface is a single client class. Skip it if you have one notification to send and no appetite for a dependency, because the documentation says you can call the HTTP API directly if no SDK exists for your language. Before you upgrade, note that the 3.x line made breaking changes and the 2.x line lives on the version_2.x branch, and check the coordinates in your build file, since the Gradle example and the Maven example in the README name different patch versions.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. wxpusher/wxpusher-sdk-java on GitHub