JuggleIM Server Java SDK

A server-side Java client for the JuggleIM REST API.

English · 简体中文

Website · Documentation · Server API · IM Server

---

imserver-sdk-java lets a trusted Java backend call JuggleIM server APIs without reimplementing request signing and response mapping. It is intended for server-side use; the app secret must never be embedded in an Android, desktop, web, or other client application.

API coverage

• Users: register, query, update, kick, online status, bans, blocks, and tags
• Messages: private messages, chatroom messages, chatroom broadcast, and recall
• Groups: create, update, dismiss, query, membership, mute, allowlist, and settings
• Chatrooms: create, destroy, query, member checks, bans, and mute controls
• Sensitive words: add, delete, query, and file import

For broader API coverage, also see the Go and Python server SDKs.

Requirements

• JDK 23 or newer (the current pom.xml compiler target)
• Maven 3.8+
• A running JuggleIM server
• An app key and app secret created by the JuggleIM admin console

Install from source

The artifact is not currently published to Maven Central. Build and install it into your local Maven repository:

git clone https://github.com/juggleim/imserver-sdk-java.git
cd imserver-sdk-java
mvn clean install

Then add the local artifact to your Maven project:

<dependency>
  <groupId>com.juggle.im</groupId>
  <artifactId>imserver-sdk-java</artifactId>
  <version>1.1</version>
</dependency>

Quick start

import com.juggle.im.JuggleIm;
import com.juggle.im.models.user.UserInfo;
import com.juggle.im.models.user.UserTokenResult;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        JuggleIm sdk = new JuggleIm(
                System.getenv("JUGGLEIM_APP_KEY"),
                System.getenv("JUGGLEIM_APP_SECRET"),
                System.getenv().getOrDefault("JUGGLEIM_API_URL", "http://127.0.0.1:9001")
        );

        UserInfo user = new UserInfo()
                .setUserId("user-001")
                .setNickname("Demo User")
                .setUserPortrait("https://example.com/avatar.png");

        UserTokenResult result = sdk.user.register(user);
        System.out.println(result);
    }
}

Run examples without committing credentials:

export JUGGLEIM_APP_KEY="your-app-key"
export JUGGLEIM_APP_SECRET="your-app-secret"
export JUGGLEIM_API_URL="http://127.0.0.1:9001"

mvn package

Then run com.juggle.im.example.user.UserExample from an IDE using the Maven project classpath. The generated JAR is not an uber-JAR, so SDK dependencies must remain on the runtime classpath.

The example classes are reference programs and call a live JuggleIM deployment. Review the IDs and payloads in an example before running it against a non-development environment.

Development

mvn test
mvn package

Source code lives under src/main/java/com/juggle/im/. The main entry point is com.juggle.im.JuggleIm, which exposes user, msgSender, group, chatroom, and sensitiveWord API groups.

Security

• Keep the app secret only on trusted backend infrastructure.
• Load credentials from environment variables or a secret manager.
• Use HTTPS for production API traffic.
• Never commit production user IDs, tokens, message content, or credentials in examples or tests.
• Report vulnerabilities privately through the repository Security tab.

Contributing

Issues and pull requests are welcome. When adding an endpoint, include request/response models, an example or unit test, and a link to the corresponding Server API.

License

Apache License 2.0