Establishing a connection

You need two things: the WebSocket URL, which comes from the discovery document, and a session or bot token.

Authenticating

Either put the credentials in the connection URL as query parameters, or send an Authenticate event once connected.

Listen for Error events from the start — that is how the server tells you the credentials are wrong, rather than by closing the socket without explanation.

On success the server sends Authenticated, then Ready with the initial state. Events start arriving after that.

Staying connected

Ping the server every ten to thirty seconds. A connection that goes quiet is dropped, and there is no distinction on the wire between a client that has nothing to say and one that has gone away.

Bots receive every event. Ordinary users do not receive UserUpdate events fanned out through servers by default — see Subscribe.

Query parameters

Parameter	Description	Values	Required
version	Protocol version in use	1	No †
format	Packet encoding, JSON by default	json, msgpack	No
token	Token for the connecting user	Session or bot token	No
ready	Which fields to include in Ready	See below	No

† version may become compulsory. Set it to 1 if you can.

Ready fields

ready may be given more than once. Asking for only what you need makes the first payload smaller, which matters most on the connections that can least afford it.

Value	Description
users	Every user you have a relation with
servers	Every server you are in
channels	Every channel you can access
members	Every member you have a relation with
emojis	Every emoji you can use
user_settings	Named settings to pre-fetch, as user_settings[<name>]
channel_unreads	Your unread state
policy_changes	Policy changes you have not seen; never sent to bots

For example:

?ready=users&ready=servers&ready=user_settings[ordering]

Put them in the connection URL:

wss://app.cordice.org/ws?version=1&format=json