Sending from your server

Your server sends events to rooms and to users with its secret, in the same chain in every package. Pages send to rooms too, as a room allows (events from the page). Only your server sends to a user.

To rooms and users

Node

await realtime.to( 'order:42' ).emit( 'updated', { status: 'paid' } );
await realtime.to( [ 'order:42', 'staff' ] ).except( tab ).emit( 'updated', { id: 42 } );   // not back to the tab that made it
await realtime.toUser( 42 ).emit( 'notice', { text: 'Your order shipped' } );

PHP

$realtime->to( 'order:42' )->emit( 'updated', [ 'status' => 'paid' ] );
$realtime->to( [ 'order:42', 'staff' ] )->except( $tab )->emit( 'updated', [ 'id' => 42 ] );
$realtime->toUser( 42 )->emit( 'notice', [ 'text' => 'Your order shipped' ] );

// Laravel: an event that implements ShouldBroadcast, on PrivateChannel( 'orders.42' ), the room orders.42
broadcast( new OrderPaid( $order ) )->toOthers();

Python

realtime.to("order:42").emit("updated", {"status": "paid"})
realtime.to(["order:42", "staff"]).except_tab(tab).emit("updated", {"id": 42})
realtime.to_user(42).emit("notice", {"text": "Your order shipped"})
await realtime.to("order:42").aemit("updated", {"status": "paid"})   # from async code: FastAPI, Starlette, async Django views

to( rooms )	one room, or up to 1,000
toUser( users ) (Python to_user)	one user, or up to 1,000: every tab and device they have open, through a room of their own WordPlus Cloud keeps. It chains with to()
except( tab ) (Python except_tab)	a tab (the browser rt.tab, sent with the request that caused it, as X-Realtime-Tab), which does not get it back. The Laravel toOthers() takes it from that header
emit( event, data, { seal } )	any name but those kept for the room itself (joined, join, leave, count, error). Data anything JSON takes, binary too, up to 1 MB. seal: false sends the data of a sealed room plain

• Sealed by default: the data of a sealed room goes sealed with its key, a copy each, and what goes to a user with their own key. The data of public rooms goes plain, together.
• Kept: a room whose rule keeps history keeps it, and the answer is the kept event ids, by room.
• A refusal throws a RealtimeError with the server code and HTTP status (errors). The Laravel broadcasting throws a BroadcastException. Send after your own work is saved: a failed send is a missed live update, not a lost change.
• A user with nothing open gets nothing: toUser() reaches the connections they have, and push stays out of this SDK for now.

Many at once

Node

await realtime.batch( [
    { rooms: 'order:42', event: 'updated', data: { status: 'paid' } },
    { users: 42, event: 'notice', data: { text: 'Paid' } },
] );   // 100 events a request

PHP

$realtime->batch( [
    [ 'rooms' => 'order:42', 'event' => 'updated', 'data' => [ 'status' => 'paid' ] ],
    [ 'users' => 42, 'event' => 'notice', 'data' => [ 'text' => 'Paid' ] ],
] );

Python

realtime.batch([
    {"rooms": "order:42", "event": "updated", "data": {"status": "paid"}},
    {"users": 42, "event": "notice", "data": {"text": "Paid"}},
])

Asking about a room

Node

await realtime.in( 'room:7' ).count();
await realtime.in( 'room:7' ).members();                      // { count, list: [ { id, info } ], next? }, their info opened
await realtime.in( 'chat:34:42' ).history( { limit: 50 } );   // { events, more }, oldest first, opened
await realtime.in( 'chat:34:42' ).forget( id );               // one kept event, forget() for all
await realtime.in( 'chat:34:42' ).kick( 43 );                 // out now

PHP

$realtime->in( 'room:7' )->members();
$realtime->in( 'chat:34:42' )->kick( 43 );

Python

realtime.in_room("room:7").members()
realtime.in_room("chat:34:42").kick(43)

Kick takes the user connections out of the room at once, and refuses them until their token expires. With the key generations kept (encryption), it also moves the room key on, so a sealed event after the kick is not theirs to read.

Webhooks

WordPlus Cloud tells your server what happens in rooms, at the address set on your app page in your WordPlus Cloud account (https://shop.example.com/api/realtime/webhook), which the package routes answer:

Node

realtime.on( 'message', async ( { room, from, data, event_id, at } ) => saveMessage( { id: event_id, room, from, text: data.text, at } ) );
realtime.on( 'user.offline', ( { user } ) => markAway( user ) );

PHP

$realtime->on( 'message', fn ( array $e ) => save_message( $e['event_id'], $e['room'], $e['from'], $e['data']['text'], $e['at'] ) );

Python

realtime.on("message", lambda e: save_message(e["event_id"], e["room"], e["from"], e["data"]["text"], e["at"]))

Event
a page event name	{ id, at, room, event, data, from, event_id }, for the events a room rule names in webhook. event_id is the id the pages saw (meta.id), what your app keeps it by
room.occupied, room.vacated	{ id, at, room }: the first one in, the last one out
member.joined, member.left	{ id, at, room, user }, in a presence room
user.online, user.offline	{ id, at, user }
*	every one of them

• Signed with a key of its own (wordplus-realtime webhook v1), and checked before a handler sees it. Sealed data comes opened.
• Batched, and sent at least once: each event has its id, so a repeat can be dropped. A request that fails is tried again, later each time, for 24 hours.