---
title: "WebSocket Connection"
url: https://docs.catalyst.zoho.com/en/sdk/python/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 Python application with sample code snippets."
last_updated: 2026-10-05T15:13:57Z
service: Cloud Scale
type: general
related_links:
  - name: "Data Streams Help"
    url: /en/cloud-scale/help/data-streams/introduction
  - name: "SDK Scopes"
    url: /en/sdk/python/v1/sdk-scopes
---

# 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 set event handlers to handle incoming messages.

## Connect and Subscribe

```python
import zcatalyst_sdk
from zcatalyst_sdk.datastreams.websocket_client import DataStreamsWebSocket
from zcatalyst_sdk.types.datastreams import DataStreamsConfig
# Initialize SDK
app_sdk = zcatalyst_sdk.initialize_app()
data_streams = app_sdk.datastreams()
# Get token pair (required to authenticate WebSocket)
token = data_streams.get_token_pair("CHANNEL_ID", user_id="USER_ID")
# Create WebSocket config
config = DataStreamsConfig(
    url=token["url"],
    zuid=token["wss-id"],
    key=token["key"],
    enable_logging=True,
)
# Create WebSocket client
websocket_client = DataStreamsWebSocket(config=config)
def on_open(event):
    # Subscribe after connection is established
    websocket_client.subscribe("0")
def on_message(event):
    # event.data: inline payload
    # event.url + event.method: bulk payload retrieval info
    print("streaming_id:", event.streaming_id)
    print("data:", event.data)
    print("url:", event.url)
    print("method:", event.method)
    # Acknowledge to receive the next message
    websocket_client.send_ack()
def on_error(event):
    # CustomEvent with code/message/data
    print("error:", event.code, event.message, event.data)
def on_close(event):
    # Close details (if any)
    print("closed:", event)
websocket_client.set_on_open(on_open)
websocket_client.set_on_message(on_message)
websocket_client.set_on_error(on_error)
websocket_client.set_on_close(on_close)
# Connect (runs WebSocket in a background thread)
websocket_client.connect()
```

## WebSocket Client Methods

The `DataStreamsWebSocket` 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>`connect()`</td>
			<td>Establishes the WebSocket connection. The connection runs in a background thread.</td>
		</tr>
		<tr>
			<td>`subscribe(subscribe_type="0")`</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). Defaults to `"0"` (live data).</td>
		</tr>
		<tr>
			<td>`unsubscribe()`</td>
			<td>Unsubscribes from the channel.</td>
		</tr>
		<tr>
			<td>`send_ack()`</td>
			<td>Sends an acknowledgement to receive the next streaming data.</td>
		</tr>
		<tr>
			<td>`close()`</td>
			<td>Closes the WebSocket connection.</td>
		</tr>
		<tr>
			<td>`is_connected()`</td>
			<td>Returns whether the connection is currently open, as a bool.</td>
		</tr>
		<tr>
			<td>`get_connection_state()`</td>
			<td>Returns the current `ConnectionState`.</td>
		</tr>
		<tr>
			<td>`get_session_info()`</td>
			<td>Returns the session information as a `Dict[str, str]`.</td>
		</tr>
	</tbody>
</table>