# Getting Started

The official Java SDK for Stream covers Chat, Video, Moderation, and Feeds. This page takes you from installing the SDK to your first API call.

## Start here

- [Backend quickstart](https://getstream.io/chat/docs/java/backend/): Generate tokens, sync users and manage channels from your server.
- [Authentication and tokens](https://getstream.io/docs/platform/authentication/): Token signing, expiry and revocation in detail.
- [Client-side overview](https://getstream.io/chat/docs/java/client-side/): Connecting users, presence and everything else that runs in your app.

## How the pieces fit together

This SDK calls the Stream API from your backend, authenticated with your API secret. Your users connect from your app with a client SDK, using a token your backend signs. Anything that needs a connected user or a live WebSocket lives in the client: initialization, guest and anonymous sessions, typing indicators and presence.

```mermaid
flowchart LR
  app[Your app] <-->|WebSocket| api[Stream API]
  backend[Your backend] -->|REST| api
  backend -. user token .-> app
```

## Stream CLI and Agent Skills

Manage Stream from your terminal with the [Stream CLI](https://getstream.io/cli/docs/), including scripting and AI-agent workflows. Install the CLI and the default [Agent Skills](https://getstream.io/agent-skills/docs/):

```bash
curl -fsSL https://getstream.io/cli.sh | bash
getstream skills
```

Then ask your agent in plain English, for example:

```text
/stream List recent channels in my app.
```

See the [CLI docs](https://getstream.io/cli/docs/) and [Agent Skills docs](https://getstream.io/agent-skills/docs/) for more.

## Setup

|        |                                                                                      |
| ------ | ------------------------------------------------------------------------------------ |
| GitHub | [github.com/GetStream/stream-sdk-java](https://github.com/GetStream/stream-sdk-java) |
| Maven  | [stream-io-repo.com](https://browse.stream-io-repo.com/releases/stream-sdk-java)     |

The SDK is published to the [Stream Maven repository](https://browse.stream-io-repo.com/releases/stream-sdk-java). Add the repository and the dependency:

Maven:

```xml
<repositories>
    <repository>
        <id>stream</id>
        <url>https://stream-io-repo.com</url>
    </repository>
</repositories>

<dependency>
    <groupId>io.getstream</groupId>
    <artifactId>stream-sdk-java</artifactId>
    <version>11.0.0</version>
</dependency>
```

Gradle:

```groovy
repositories {
    mavenCentral()
    maven { url "https://stream-io-repo.com" }
}

dependencies {
    implementation 'io.getstream:stream-sdk-java:11.0.0'
}
```

Upgrading from 10.x: see the [v10 to v11 migration guide](https://github.com/GetStream/stream-sdk-java/blob/11.0.0/MIGRATION_v10_to_v11.md).

Initialize the client with your API key and secret (available on the [Dashboard](https://getstream.io/signin/?product=chat)):

```java
import io.getstream.services.framework.StreamSDKClient;

var client = new StreamSDKClient("your-api-key", "your-api-secret");
```

You can also load credentials from environment variables (`STREAM_API_KEY`, `STREAM_API_SECRET`):

```java
var client = new StreamSDKClient();
```

## Server-side token

Your backend generates a user token that the client SDKs use to authenticate. A typical place to issue this token is during login or registration.

```java
var token = client.tokenBuilder().createToken("user-id");
// return the token to the client app
```

Tokens with an expiry (in seconds):

```java
var token = client.tokenBuilder().createToken("user-id", 3600);
```

For token expiry and revocation details, see [Authentication and tokens](https://getstream.io/docs/platform/authentication/).

## Making your first API call

Create a user, open a channel, and send a message:

```java
import io.getstream.models.*;
import io.getstream.services.Chat;
import java.util.Map;

// Upsert a user
client.updateUsers(UpdateUsersRequest.builder()
    .users(Map.of("john", UserRequest.builder().id("john").name("John").build()))
    .build()).execute();

// Create or join a channel
Chat chat = client.chat();
chat.channel("messaging", "hello-world")
    .getOrCreate(GetOrCreateChannelRequest.builder()
        .data(ChannelInput.builder()
            .createdByID("john")
            .build())
        .build());

// Send a message
chat.channel("messaging", "hello-world")
    .sendMessage(SendMessageRequest.builder()
        .message(MessageRequest.builder()
            .text("Hello, Stream!")
            .userID("john")
            .build())
        .build());
```

## What's next

Once your first message is through, these are good places to go deeper:

- [Creating channels](https://getstream.io/chat/docs/java/creating-channels/): Channel types, custom data and everything else about setting up conversations.
- [Sending messages](https://getstream.io/chat/docs/java/send-message/): Attachments, custom fields and the rest of the message API.
- [Webhooks](https://getstream.io/docs/platform/webhooks/): React to chat events from your own backend.

## FAQ

**Which webhook events does chat send?**

The [event catalogue](https://getstream.io/chat/docs/java/webhook-events/) lists every webhook event and most payloads.

**Can I check messages before they're delivered?**

Yes, with the [before message send webhook](https://getstream.io/chat/docs/java/before-message-send-webhook/).

**Does this SDK cover other Stream products?**

Yes. Each [backend SDK](https://getstream.io/docs/platform/backend-sdks/) covers every product; build one client and reuse it.

**Are server-sent messages moderated?**

Not by default. Set `forceModeration` to `true` when sending. See [chat moderation](https://getstream.io/moderation/docs/java/integrations/stream-chat/#server-side-integration).

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/java/](https://getstream.io/chat/docs/java/).