---
title: "WebSocket Connection"
url: https://docs.catalyst.zoho.com/en/sdk/java/v1/cloud-scale/data-streams/websocket-connection/
description: "This page describes how to connect to a Data Streams channel over WebSocket and subscribe to real-time data in your Java application with sample code snippets."
last_updated: 2026-10-05T15:13:57Z
service: Cloud Scale
type: general
related_links:
  - name: "Data Streams"
    url: /en/cloud-scale/help/data-streams/introduction
---

# WebSocket Connection

[Catalyst Data Streams](https://docs.catalyst.zoho.com/en/cloud-scale/help/data-streams/introduction/) enables clients to receive real-time data by establishing a WebSocket connection to a channel. The client listens for published messages and processes them as they are received.

To subscribe to a channel, you must first generate a token pair, then create a WebSocket client with the token credentials, and finally add event listeners to handle incoming messages.

#### Sample Code Snippet

**Package Imports**

```java
import com.zc.component.datastream.ZCDatastream;
import com.zc.component.datastream.beans.ZCCustomEvent;
import com.zc.component.datastream.beans.ZCDataStreamMessageEvent;
import com.zc.component.datastream.beans.ZCDataStreamsConfig;
import com.zc.component.datastream.beans.ZCTokenResponse;
import com.zc.component.datastream.websocket.ZCDataStreamsEventListener;
import com.zc.component.datastream.websocket.ZCDataStreamsWebSocket;
```

```java
//Create a Data Streams instance
ZCDatastream datastream = ZCDatastream.getInstance();

//Define channel ID and user ID
String channelId = "30772000000631098";
Long userId = 30772000000631094L;

//Generate token pair
ZCTokenResponse tokenResponse = datastream.getTokenPair(channelId, userId);

//Extract token credentials
String key = tokenResponse.getKey();
String zuid = tokenResponse.getWssId();
String url = tokenResponse.getUrl();

//Create WebSocket configuration
ZCDataStreamsConfig config = new ZCDataStreamsConfig(
    url,
    zuid,
    key,
    false
);

//Create WebSocket client
ZCDataStreamsWebSocket webSocketClient = datastream.createWebSocketClient(config);

//Add event listener to handle WebSocket events
webSocketClient.addEventListener(new ZCDataStreamsEventListener() {
    @Override
    public void onOpen(ZCCustomEvent event) {
        //Subscribe after WebSocket opens
        webSocketClient.subscribe("-2");
    }

    @Override
    public void onMessage(ZCDataStreamMessageEvent event) {
        //Handle event payload or bulk URL info
        if (event.getData() != null) {
            System.out.println("Data: " + event.getData());
        } else if (event.getUrl() != null && event.getMethod() != null) {
            System.out.println("API URL: " + event.getUrl());
            System.out.println("Method: " + event.getMethod());
        }

        //Acknowledge to receive the next message
        webSocketClient.sendAck();
    }

    @Override
    public void onClose(ZCCustomEvent event) {
        System.out.println("Closed: " + event.getMessage());
    }

    @Override
    public void onError(ZCCustomEvent event) {
        //Log error
        System.err.println("Error: " + event.getMessage());
    }

    @Override
    public void onPong(ZCCustomEvent event) {
        System.out.println("Pong: " + event.getMessage());
    }
});
```

### WebSocket Client Methods

The `ZCDataStreamsWebSocket` client provides the following methods to manage the WebSocket connection and subscription.

<table class="content-table">
	<thead>
		<tr>
			<th class="w30p">Method</th>
			<th class="w70p">Description</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>`subscribe(String subscribeType)`</td>
			<td>Subscribes to the channel with the specified [subscribe type](https://docs.catalyst.zoho.com/en/cloud-scale/help/data-streams/implementation/subscribe-websocket/#choose-your-subscriber-type). Throws `ZCDataStreamException`.</td>
		</tr>
		<tr>
			<td>`subscribe()`</td>
			<td>Subscribes to the channel with the default subscribe type. Throws `ZCDataStreamException`.</td>
		</tr>
		<tr>
			<td>`unsubscribe()`</td>
			<td>Unsubscribes from the channel. Throws `ZCDataStreamException`.</td>
		</tr>
		<tr>
			<td>`sendAck()`</td>
			<td>Sends an acknowledgement to receive the next streaming data.</td>
		</tr>
		<tr>
			<td>`close()`</td>
			<td>Closes the WebSocket connection manually.</td>
		</tr>
		<tr>
			<td>`isConnected()`</td>
			<td>Returns whether the connection is currently open, as a boolean.</td>
		</tr>
		<tr>
			<td>`getConnectionState()`</td>
			<td>Returns the current connection state as a String.</td>
		</tr>
		<tr>
			<td>`getSessionInfo()`</td>
			<td>Returns the `ZCSessionInfo` of the active session.</td>
		</tr>
	</tbody>
</table>