0b7c132ace
* docs: initialise new docs with docusaurus * chore: sign off Signed-off-by: izzy <me@insrt.uk> * chore: lock pnpm version in package.json Signed-off-by: izzy <me@insrt.uk> * ci: specify package json to load pnpm version from Signed-off-by: izzy <me@insrt.uk> * docs: update repo. lifecycle details Signed-off-by: izzy <me@insrt.uk> * docs: add external links to for-web, for-android chore: add default.nix to docs * docs: correct headings in contrib * ci: use cache dependency path * fix: docusaurus configuration --------- Signed-off-by: izzy <me@insrt.uk>
3.5 KiB
Establishing a connection
To get started, you should have:
- A WebSocket URL, which is found from the API root.
- A valid session or bot token.
You may authenticate in one of two ways:
- Include credentials in the connection URL, see Query Parameters.
- Sending an Authenticate event to the server.
You should listen out for Error events to find out if your credentials are incorrect or if something goes wrong here.
After authenticating, the server will respond with Authenticated then it will send a Ready event containing useful data.
The server will now start sending relevant events as they come in.
You should Ping the server every 10 to 30 seconds to prevent your connection being dropped.
Bots receive all events, normal users do not receive UserUpdate events fanned out through servers by default, read more here.
Query Parameters
The Bonfire service supports additional query parameters:
| Parameter | Description | Values | Required |
|---|---|---|---|
version |
Describes the protocol version in use. | 1 |
No † |
format |
In what format to send packets, default is JSON. | json, msgpack |
No |
token |
token for authenticating the connecting user. | Session or bot token | No |
ready |
Fields to include in the Ready event payload, by default all are sent |
See Below | No |
† version may become compulsary in the future, please set it to 1 if you can.
Ready Fields
The ready query parameter can be passed multiple times to specify multiple fields, supported fields are:
| Value | Description |
|---|---|
users |
Includes all users you have a relation with. |
servers |
Includes all servers you are in. |
channels |
Includes all channels you have access to. |
members |
Includes all members you have a relation with. |
emojis |
Includes all emojis you have access to. |
user_settings |
Specify which settings to pre-fetch, specify a setting by setting the value to user_settings[<setting_name>]. |
channel_unreads |
Includes all channel unreads you have. |
policy_changes |
Includes all new policy changes you should be aware of, this is not sent to bots. |
For example:
?ready=users&ready=servers&ready=user_settings[ordering]
You may specify these in the connection URL: wss://stoat.chat/events?version=1&format=json.