# imserver-sdk-java

**Repository Path**: juggleim/imserver-sdk-java

## Basic Information

- **Project Name**: imserver-sdk-java
- **Description**: Java 语言版本的 JuggleIM API SDK
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-10-17
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# JuggleIM Server Java SDK

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

[![License](https://img.shields.io/github/license/juggleim/imserver-sdk-java?style=flat-square)](./LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/juggleim/imserver-sdk-java/ci.yml?branch=master&style=flat-square&label=CI)](https://github.com/juggleim/imserver-sdk-java/actions/workflows/ci.yml)
[![Java](https://img.shields.io/badge/Java-23+-f89820?style=flat-square&logo=openjdk)](./pom.xml)
[![Stars](https://img.shields.io/github/stars/juggleim/imserver-sdk-java?style=flat-square)](https://github.com/juggleim/imserver-sdk-java/stargazers)

**English** · **[简体中文](./README_zh.md)**

[Website](https://www.juggle.im/) ·
[Documentation](https://www.juggle.im/docs/guide/intro/) ·
[Server API](https://www.juggle.im/docs/server/api/) ·
[IM Server](https://github.com/juggleim/im-server)

</div>

---

`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](https://github.com/juggleim/imserver-sdk-go) and
[Python](https://github.com/juggleim/imserver-sdk-python) server SDKs.

## Requirements

- JDK 23 or newer (the current `pom.xml` compiler target)
- Maven 3.8+
- A running [JuggleIM server](https://github.com/juggleim/im-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:

```bash
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:

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

## Quick start

```java
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:

```bash
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

```bash
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](https://www.juggle.im/docs/server/api/).

## License

[Apache License 2.0](./LICENSE)