WebSocket API

Connect to PieSocket directly over a raw WebSocket connection, no official SDK required. Useful if you're integrating from a platform or language we don't have an SDK for, or building your own client library.

Connecting

wss://CLUSTER_ID.piesocket.com/v4/CHANNEL_ID?api_key=API_KEY

PieSocket currently supports two protocol versions, v3 and v4, both reachable at the same cluster domain, just swap the path segment. New integrations should generally use v4, it supports subscribing to multiple channels over a single connection, presence membership aware of user identity rather than just connection count, and a few other improvements over v3.

This page covers the concepts shared by both versions at a high level. For exact message formats, see:

WebSocket Parameters

Cluster ID

Your cluster ID is shown alongside your API key credentials in your PieSocket dashboard.

API Key

Generate an API key for free from your PieSocket dashboard.

Channel ID

The channel ID identifies the topic messages are published and subscribed to, only clients connected to the same channel receive each other's messages, even if they're using the same PieSocket cluster.

Choosing a channel ID
Max 200 characters long.
Allowed characters: [a-z], [A-Z], [0-9], _ (underscore) and - (hyphen).
Messages are delivered only to clients on the same channel.
A single connection can subscribe to more than one channel (V4 only).
The sender doesn't receive their own message by default, use notify_self to change this.

Notify Self

By default, PieSocket doesn't deliver a message back to the connection that sent it. For example, if three connections A, B, and C are on the same channel, a message sent by A is only delivered to B and C.

To receive your own messages, add notify_self=1 to your connection URL:

wss://demo.piesocket.com/v4/CHANNEL_ID?api_key=API_KEY&notify_self=1

User Identity

There are two ways to set a connection's identity:

Unsecured: pass &user=id on the connection URL. Simple, but anyone who can reach your API key can claim any identity.
Secure: sign a JWT on your server and pass it as the jwt parameter, with the identity in its user claim. See Authentication.

JWT Token

A JWT is required if you've enabled authentication for your API key, or you're connecting to a private- prefixed channel. It's passed as the jwt query parameter (or a jwt header) and verifies the connection's permission to join the channel.

Read the Authentication guide for how to generate one.

Private Channels

Channels prefixed private- require a valid JWT to connect.

Learn more: Authentication

Presence Channels

Presence channels emit events when connections join or leave, so you can maintain a list of who's currently online.

Channels prefixed presence- are presence channels automatically, on any other channel name, pass presence=1 to enable the same behavior.

See the protocol reference for the exact member list/join/leave message formats, or build a chatroom with presence for a working example.

Rate Limits

PieSocket doesn't impose a hard rate limit on connections or messages by default, build the experience your users need. That said, usage well outside your plan's expected range may get flagged for abuse and result in your account being suspended.

Command Messages

Command messages are reserved plain-text messages, not JSON, that query the server directly. The reply is sent only to the connection that sent the command.

Command	Reply
cmd_status	`{"system":{"connection_count": 1}}`, number of connections on the channel
cmd_ping	`{"system":"pong"}`

Getting started

See the example implementation to build a chatroom with JavaScript by connecting directly to the WebSocket API, or jump to the full V3 / V4 protocol reference if you're building your own client library.