WebSocket API

WebSocket API gives you the power to integrate PieSocket's Scalable PubSub infrastructure into any platform using 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/CHANNEL_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.

Channel ID

Channel 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 channel, and not other channels even if they are using the same API key.

Choosing a channel ID
Channel ID can be max 30 characters long.
Channel ID can contain characters [a-z], [A-Z], [0-9].
Channel ID can contain special characters _ (underscore) and - (hyphen).
Messages are transmitted to only the clients on the same channels.
One client is allowed to connect to multiple channels.
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 channel 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 Channel permissions.

Read our Authentication guide to learn more about JWT parameter.

Notify Self

By default, the WebSocket 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/CHANNEL_ID?api_key=API_KEY&notify_self=1

Private Channels

Private channels require authentication for subscribing to them.

All channels prefixed with private- are Private channels.

See: Authentication section

Presence Channels

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

All channels prefixed with presence- are Presence channels.

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

Realtime Blockchain

Realtime Blockchain feature allows you to send messages to other users that are verifiable on the Ethereum blockchain.

A permanent record/contract is created between the sender and the receiver on Blockchain, with input data containing the encrypted PieSocket payload, which can be decoded using your API secret.

Messages sent over the blockchain Channels are 100% trustworthy and can serve as legal evidence of the communication between the sender and the receiver.

Getting started: Realtime Blockchain Documentation

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

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

cmd_ping

Responds with "pong"

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

Getting started

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