WebSocket Connection

Catalyst Data Streams 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

copy
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.

Method Description
connect() Establishes the WebSocket connection. The connection runs in a background thread.
subscribe(subscribe_type=“0”) Subscribes to the channel with the specified subscribe type. Defaults to “0” (live data).
unsubscribe() Unsubscribes from the channel.
send_ack() Sends an acknowledgement to receive the next streaming data.
close() Closes the WebSocket connection.
is_connected() Returns whether the connection is currently open, as a bool.
get_connection_state() Returns the current ConnectionState.
get_session_info() Returns the session information as a Dict[str, str].

Last Updated 2026-10-05 20:43:57 +0530 IST

ON THIS PAGE