PieSocket Events
The event shape
PieSocket doesn't enforce a message schema, any string or JSON value works, see Sending messages. By convention, our SDKs and dashboard tools structure messages as an event instead:
{
"event": "new-tweet",
"data": "Hello from @pie_host",
"meta": "uuid-1",
"system::to": "john"
}
| Field | Required | Details |
|---|---|---|
| event | Yes | The event name, this is what your listeners subscribe to. |
| data | Yes | The event's payload. |
| meta | No | Extra metadata for your own app's use, PieSocket doesn't read or act on it. |
| system::to | No | A user ID, or an array of them, deliver this message only to connections identified as one of these users. See Identifying a user for how a connection gets an identity. |
Sending an event
channel.publishEvent('new-tweet', 'Hello from @pie_host', 'uuid-1');
channel.publishEvent("new-tweet", "Hello from @pie_host", "uuid-1");
channel.publishEvent("new-tweet", data: "Hello from @pie_host", meta: "uuid-1");
channel.publishEvent("new-tweet", data: "Hello from @pie_host", meta: "uuid-1")
If you'd rather build the event as an object first (to pass it around, queue it, reuse it), every SDK also has a PieSocketEvent class with chainable setData()/setMeta() and a plain publish(event) method that takes one:
PieSocketEvent newTweet = new PieSocketEvent("new-tweet");
newTweet.setData("Hello from @pie_host");
newTweet.setMeta("uuid-1");
channel.publish(newTweet);
From a backend, publish over the REST API instead, no SDK required.
Listening for events
channel.listen('new-tweet', (data, meta) => {
// ...
});
Every SDK exposes the same listen(eventName, callback) method. Pass * as the event name to catch every event on the channel, regardless of name:
channel.listen('*', (event, data, meta) => {
// ...
});
System events
These event names differ by protocol version, single colon on V3, double colon on V4. They arrive like any other event, through listen(), no special handling needed:
V3
| Event | Fired when | Required config |
|---|---|---|
| system:member_joined | A member joins a presence channel | presence- prefix or presence=1 |
| system:member_left | A member leaves a presence channel | presence- prefix or presence=1 |
| system:error | The server rejects the connection (bad key, failed auth, etc.), see Errors | None |
V4
| Event | Fired when | Required config |
|---|---|---|
| system::member_joined | A member joins a presence channel | presence- prefix or presence=1 |
| system::member_left | A member leaves a presence channel | presence- prefix or presence=1 |
| system::error | The server rejects the connection (bad key, failed auth, etc.), see Errors | None |
The rest are the same on both versions:
| Event | Fired when | Required config |
|---|---|---|
| * | Every event, whatever its name | None |
message (JavaScript only, via on()) | Any frame arrives on the connection, parsed or not | None |
error (JavaScript only, via on()) | The connection errors out | None |
close (JavaScript only, via on()) | The connection closes | None |
member_joined and member_left fire the same way as any other event, through listen(). See Presence channels for the full payload shapes.
Connection lifecycle (JavaScript only)
There's no "connected" event to listen for, the channel is ready as soon as subscribe()'s promise resolves:
const channel = await piesocket.subscribe('chat-room');
// channel is connected and ready here
For everything after that, the JavaScript SDK has a separate on(name, callback) method, distinct from listen(), for the underlying WebSocket connection itself rather than named events:
| Name | Fires when |
|---|---|
| message | Any frame arrives on the connection, parsed or not. |
| error | The connection errors out. |
| close | The connection closes. |
channel.on('error', (e) => {
// ...
});
This error is a transport-level WebSocket error, not the same thing as the system:error/system::error event above, that one is a message the server sent you, this one fires when the browser's WebSocket object itself errors out.