---
sidebar_position: 14
---

# Browser reference: `@wordplus/realtime`

## `connect( options )` → `Promise<Realtime>`

| Option | |
|---|---|
| `site` | your app's key |
| `endpoint` | your routes, `/api/realtime` by default; in full in an app |
| `headers` | sent with every request to your routes, such as a CSRF token |
| `worker` | your app's `realtime-worker.js`: every tab shares one connection |
| `rooms` | your app's `realtime-rooms.min.js`, for group calls |
| `keys` | `{ entries, identity }` from your server's `config()`: no request before connecting |
| `ring` | `false`: this page holds no line, so calls don't ring here |
| `server`, `path`, `api` | WordPlus Cloud by default |

Or your server's `config()` as it is: `connect( config )`. `connectNow()` connects without asking your keys route first.

## `Realtime`

| Member | |
|---|---|
| `subscribe( name )` | → `Subscription`, the same one for the same name |
| `channel( name )`, `unsubscribe( name )` | |
| `users( ids )` | → `Promise<{ [id]: profile }>`: your users from the directory, opened ([encryption](encryption.md#your-users)) |
| `calls()` | → `Promise<Calls>`, loading the call engine the first time ([calls](calls.md)) |
| `callScreen( { strings } )` | → `Promise<boolean>`: starts the call screen |
| `tab` | this tab's name, for a publish's `except` |
| `connected` | |
| `on( event, fn )`, `off( event, fn? )` | `connected`, `disconnected`, `moved`, `error` (`{ code }`: the connection refused) |
| `close()` | |
| `channels` | the underlying `Channels` |

## `Subscription`

| Member | |
|---|---|
| `name`, `kind` | the channel; `public`, `private` or `presence` |
| `state`, `error` | `pending`, `subscribed`, `failed`, `ended`; why it failed |
| `on( event, fn )`, `once`, `off` | a channel's event, `fn( data, { user_id } )`, opened; or `realtime:subscribed`, `realtime:error`, `realtime:member_added`, `realtime:member_removed`, `realtime:unopened` |
| `trigger( event, data )` | → `Promise`: a `client-…` event to the others |
| `members()`, `memberCount` | a presence channel's |
| `unsubscribe()` | |

## `Calls`

| Member | |
|---|---|
| `start( name, { to, type } )` | → `Promise<Call>` |
| `room( name, { type } )` | → `Promise<Room>` |
| `incoming()` | the calls ringing now |
| `stopRinging()` | the page holds the line no more |
| `on( 'incoming' \| 'error', fn )` | |

`Incoming`: `id`, `call`, `from`, `info`, `type`, `state`, `accept()`, `decline( 'declined' | 'busy' )`, `on( 'over', fn )`.

`Call`: `state` (`ringing`, `connecting`, `connected`, `reconnecting`, `ended`), `path` (`direct`, `relay`, `room`), `peer` (`{ user, info }`), `remote` (`{ camera, microphone, screen, screenAudio, quality }`), `endReason`, `setTrack( source, track )`, `end()`, and `on()` for `state`, `path`, `remote`, `waiting`, `ended`.

`Room`: `state`, `people()` (`{ user, info, camera, microphone, screen, screenAudio, speaking }`), `setTrack( source, track )`, `leave()`, `livekit`, and `on()` for `state`, `waiting`, `person`, `person_left`, `speakers`, `ended`.

A remote track has `attach( element )`, `detach( element? )` and `mediaStreamTrack`.

## Keys

`keyring()` is the page's: `open( value )`, `openJson( value )`, `seal( text, label )`, `ensure( labels )`, `has( label )`. `labelOf( value )` names the key a sealed value needs ([encryption](encryption.md)).