WebSocket Server API

WebSocket API enables you the power to integrate PieSocket's Scalable PubSub infrastructure into any platform using our Client SDks or a third-party WebSocket client.

What is WebSocket

A WebSocket connection is a long-lived bi-directional HTTP connection that stays open in your browser/app/client and can receive data instantly. All modern browsers support WebSockets.

We provide a secure WebSocket server API that takes away your worries of setting up and managing a scalable WebSocket server infrastructure.

See the getting started guide section for examples on how to use the service.

WebSocket Server API

Using PieSocket's WebSocket Server API, you can focus on doing what you do best and leave the complexities of the scalable bi-directional server infrastructure to us.

wss://CLUSTER_ID.piesocket.com/v3/ROOM_ID?api_key=API_KEY

Following is a demo API endpoint, it uses our demo API key available to public to make getting started with PieSocket a piece of cake:

wss://demo.piesocket.com/v3/1?api_key=oCdCMcMPQpbvNjUIzqtvF1d2X2okWpDQj4AwARJuAgtjhzKxVEjQU6IdCjwm

Parameters

Cluster ID

You can find the Cluster-ID with API key credentials in your PieSocket account.

API Key

You can generate an API Keys from your PieSocket account for free.

Room ID

Room ID can be any string with allowed characters mentioned below.

When a message is sent, it is distributed only to the members of that particular room, and not other rooms even if they are using the same Channels cluster.

Choosing a Room ID
Room ID can be max 30 characters long.
Room ID can contain characters [a-z], [A-Z], [0-9].
Room ID can contain special characters _ (underscore) and - (hyphen).
Messages are transmitted to only the clients in the same room.
One client is allowed to connect to multiple rooms.
Sender of a message will not receive their own message, use notify_self to enable.

User identity

There are two ways to set user identity for a room member.

  1. Unsecured way: This is easy to implmenet but unsecured way to set user id/name. Pass &user=id to the WebSocket endpoint to set user's id or name.

  2. The right way: Use a JWT token signed by your server, this is the secure way to set user identity. You can pass the user id/name/json into JWT payload, read more in the authentication section

JWT Token

JWT token is required if you have enabled authentication for your API key. It is a query string parameter and is used to verify room permissions.

Read our Authentication guide to learn more about JWT parameter.

Notify Self

By default, the Channels server does not publish a message to its original sender. For example, if three members A, B, and C are connected to a channel. Messages sent by A, will only be delivered to B and C.


To enable receiving self messages, add &notify_self=1 to your server connection URL as shown below.

wss://demo.piesocket.com/v3/ROOM_ID?api_key=API_KEY&notify_self=1

Private Channel Rooms

Private channel rooms require authentication for subscribing to them.

All rooms are prefixed with private- are Private channel rooms.

Learn more: See Authentication section

Presence Channel Rooms

Presense channel rooms emit events when users join or leave the channel, enabling you to maintain an array of online/connected members.

All rooms prefixed with presence- are Presence channel rooms.

To enable presence events on any room, pass &presence=1 to the WebSocket endpoint as a query string.

Example: Building a chatroom with Presence feature

Rate limit

We implement following rate limits in addition to the daily messages quota and concurrent connections limit.

- 10 connections/second/IP address
- 20 messages/second/channel

Command messages

Command messages are reserved string messages that start with cmd_, and they are used to send queries to the WebSocket server.

&notify_self should must be used to take advantage of cmd_ commands, since their response is sent only to the original sender of the message.

Following is a list of command messages:

cmd_status

Responds with number of connected clients to the room.

Example: Sending "cmd_status" to a Channels room, results in following response: {"system":{"connection_count":1}}

cmd_ping

Responds with "pong"

Example: Sending "cmd_ping" to a Channels room, results in following response: {"system":"pong"}

Getting started

See the example implementation to learn how to build a chatroom with JavaScript by connecting directly to the WebSocket Server API.