Official Java SDK for Stream

Check out our:

• ⭐ Chat API
• 📱 Video API
• 🔔 Activity Feeds

Features

• Video call creation and management
• Chat session creation and management
• Token generation for user authentication

Installation

dependencies {
implementation("io.getstream:stream-sdk-java:$streamVersion")
}

Migrating from stream-chat-java?

If you are currently using stream-chat-java, we have a detailed migration guide with side-by-side code examples for common Chat use cases. See the Migration Guide.

✨ Getting started

Configuration

To configure the SDK you need to provide required properties.

Property	ENV	Default	Required
io.getstream.apiKey	STREAM_API_KEY	-	Yes
io.getstream.apiSecret	STREAM_API_SECRET	-	Yes
io.getstream.timeout	STREAM_API_TIMEOUT	10000	No

Users and Authentication

importio.getstream.services.frameworks.StreamSDKClient;
importio.getstream.models.UserRequest;
varclient = newStreamSDKClient("apiKey", "apiSecret");
// sync two users using the UpdateUsers method, both users will get inserted or updatedList<UserRequest> userRequests =
List.of(
UserRequest.builder()
.id("tommaso-id")
.name("tommaso")
.role("admin")
.custom(Map.of("country", "NL"))
.build(),
UserRequest.builder()
.id("thierry-id")
.name("thierry")
.custom(Map.of("country", "US"))
.build());
UpdateUsersRequestupdateUsersRequest =
UpdateUsersRequest.builder()
.users(userRequests.stream().collect(Collectors.toMap(UserRequest::getId, x -> x)))
.build();
client.updateUsers(updateUsersRequest).execute();
// Create a JWT token for the user to connect client-side (e.g. browser/mobile app)// token expires in 24 hoursclient.tokenBuilder().createToken("john", 24 * 60 * 60);

Video API - Calls

To create a video call, use the client.video.call method:

vartestCall = client.video().call("default", UUID.randomUUID().toString());
// create call if it doesn't exist or get the existing onecall.getOrCreate(
GetOrCreateCallRequest.builder()
.data(
CallRequest.builder()
.createdByID("sacha")
.members(members)
.custom(Map.of("color", "blue"))
.build())
.build());

Note: When constructing models, always use the builder pattern (e.g. UserRequest.builder().id("id").build()). While some generated models expose positional constructors (for example via Lombok's @AllArgsConstructor), their parameter order is not part of the public API and may change between releases; using positional constructors is therefore strongly discouraged and may break across SDK updates.

Logging

The SDK emits structured log events through SLF4J (dependency org.slf4j:slf4j-api). Inject your own SLF4J Logger via StreamClientOptions.setLogger(...). When no logger is injected the SDK logs to a no-op logger, so nothing is emitted unless you opt in. The SDK never changes the logger's level; that stays entirely under your control through your SLF4J binding.

org.slf4j.Loggerlogger = org.slf4j.LoggerFactory.getLogger("io.getstream");
varoptions = newStreamClientOptions().setLogger(logger);
varclient = newStreamSDKClient("apiKey", "apiSecret", options);

Four events are emitted:

Event	Level	When
client.initialized	INFO	once, at client construction (SDK name/version and the effective client config)
http.request.sent	DEBUG	before each request (method, path, query)
http.response.received	DEBUG	after any response, including 4xx/5xx (status code, body size, duration)
http.request.failed	ERROR / DEBUG	ERROR on a final transport failure (no HTTP response received; error type, message, duration). DEBUG once per attempt that gets retried (see Retry); a retried rate-limit (429) DEBUG log omits the error type field, since it isn't a transport error.

Redaction is mandatory and cannot be disabled: query values for api_key, api_secret and token are replaced with <redacted>, and the top-level JSON body keys api_secret, token and password are redacted. The events never log request/response headers.

Request and response bodies are not logged by default. Call StreamClientOptions.setLogBodies(true) to opt in (secret body keys are still redacted); doing so emits a one-time warning at construction. Do not enable body logging in production unless you accept the risk of logging sensitive payloads.

Deprecated: the older HttpLoggingInterceptor is deprecated in favour of these SLF4J events. It is kept for backward compatibility and now redacts secret headers and secret body keys in its own output.

Retry

Auto-retry is opt-in and disabled by default: the client makes exactly one attempt and surfaces errors unchanged. Enable it via StreamClientOptions.setRetry(...):

varoptions =
newStreamClientOptions()
.setRetry(
newRetryConfig()
.setEnabled(true)
.setMaxAttempts(3) // default: 3
.setMaxBackoff(Duration.ofSeconds(30))); // default: 30svarclient = newStreamSDKClient("apiKey", "apiSecret", options);

Only idempotent GET/HEAD requests are retried, and only for HTTP 429 (rate limited, unless the server marked it unrecoverable) or a transport-level failure (connection reset, timeout, DNS failure, TLS handshake failure). Writes (POST/PUT/PATCH/DELETE) and any other 4xx/5xx response are never retried. The delay before each retry honors the Retry-After header when present (clamped to MaxBackoff); otherwise it uses full-jitter exponential backoff. When attempts are exhausted, the last attempt's error is surfaced.

Development

To run tests, create the local.properties file using the local.properties.example and adjust it to have valid API credentials:

cp local.properties.example local.properties

Then run the tests:

 ./gradlew test

Format the code:

./gradlew spotlessApply

Generate code from spec

To regenerate the Java source from OpenAPI, just run the ./generate.sh script from this repo.

Note

Code generation currently relies on tooling that is not publicly available, only Stream devs can regenerate SDK source code from the OpenAPI spec.

Contributing

Contributions are welcome! Please read the contributing guidelines to get started.