API Reference: Realtime Connection

Below are the parameters and return data type references for the methods in TypeScript format.

connectRealtime

connectRealtime(cb: RealtimeCallback): Promise<WebSocket | void>

On the initial connection the returned promise resolves to undefined (the WebSocket is delivered through the callback cb). On subsequent calls it resolves to the already-established WebSocket.

See RealtimeCallback

Errors

{
  code: 'INVALID_REQUEST';
  message: "Callback must be a function.";
}
|
{
  code: 'ERROR';
  message: "Skapi: WebSocket connection error.";
}

postRealtime

postRealtime(
    message: SubmitEvent | any,
    recipient: string, // User's ID or a group name
    notification?: {
      title: string;
      body: string;
      config?: {
        always: boolean; // When true, notification will always trigger the receiver's device regardless their connection state.
      }
    }
): Promise<{ type: 'success', message: 'Message sent.' }>

Errors

{
  code: 'INVALID_REQUEST';
  message: "No realtime connection. Execute connectRealtime() before this method.";
}
|
{
  code: 'INVALID_REQUEST';
  message: "User has not joined to the recipient group. Run joinRealtime('...')";
}
|
{
  code: 'INVALID_REQUEST';
  message: "Realtime connection is not open. Try reconnecting with connectRealtime().";
}

joinRealtime

joinRealtime(params: {
  group: string | null, // Group name, or null to leave group
}
): Promise<{ type: 'success', message: string }>

Errors

{
  code: 'INVALID_REQUEST';
  message: "No realtime connection. Execute connectRealtime() before this method.";
}

getRealtimeGroups

getRealtimeGroups(params?: {
        searchFor?: 'group' | 'number_of_users';
  value?: string | number; // Group name or number of users
        condition?: '>' | '>=' | '=' | '<' | '<=' | '!=' | 'gt' | 'gte' | 'eq' | 'lt' | 'lte' | 'ne';
  range?: string | number; // Cannot be used with condition.
    } | null,
    fetchOptions?: FetchOptions
): Promise<DatabaseResponse<{ group: string; number_of_users: number; }>>

getRealtimeUsers

getRealtimeUsers(params?: {
        group?: string; // Group name. Defaults to the currently joined realtime group.
        user_id?: string; // User ID in the group
    },
    fetchOptions?: FetchOptions
): Promise<DatabaseResponse<{ user_id:string; cid:string; }[]>>

See FetchOptions

See DatabaseResponse

closeRealtime

closeRealtime(): Promise<void>

connectRTC

connectRTC(
  params: {
    cid: string;
    ice?: string | Array<{ urls: string | string[]; username?: string; credential?: string }>; // Omitted: Skapi's STUN server and TURN relay, with a credential for the user. See "The relay" in the WebRTC guide
    icePolicy?: 'all' | 'relay'; // 'relay' sends everything through the relay, even where a direct path exists
    media?: MediaStream | {
      audio?: boolean | MediaTrackConstraints; // the microphone
      video?: boolean | MediaTrackConstraints; // the camera
      screen?: boolean | (DisplayMediaStreamOptions & { contentHint?: 'text' | 'detail' | 'motion' }); // the screen, with getDisplayMedia()
    }; // Omitted, or everything false: no media. A MediaStream of your own is sent as it is.
    receive?: { audio?: boolean; video?: boolean }; // take a kind you do not send yourself, without a renegotiation
    encoding?: {
      video?: { codecs?: string[]; maxBitrate?: number; maxFramerate?: number; scaleResolutionDownBy?: number }; // codec names in the preferred order; bits per second
      audio?: { codecs?: string[]; maxBitrate?: number };
    };
    channels?: Array<RTCDataChannelInit | 'default' | 'text-chat' | 'file-transfer' | 'video-chat' | 'voice-chat' | 'gaming'>; // Omitted: ['default']. A string that is not a preset opens a channel of that name.
    meta?: Record<string, any>; // a JSON object the other side reads on its rtc:incoming message, before it answers
    ringTimeout?: number; // milliseconds to wait for an answer; none by default
  },
  callback: (e: RTCEvent) => void
): Promise<RTCConnector>

The answering side calls connectRTC() on its rtc:incoming message with the same options but cid, meta and ringTimeout: see RTCReceiverParams. Both resolve, once the call is up, with the running call: see RTCResolved.

See RTCConnector

See RTCEvent

Errors

{
  code: 'DEVICE_NOT_FOUND';
  message: "Requested media device not found.";
}
|
{
  code: 'INVALID_REQUEST';
  message: 'Data channel with the protocol "{protocol name}$" already exists.';
}
|
{
  code: 'INVALID_REQUEST';
  message: 'Media stream is only supported on either localhost or https.';
}
|
{
  code: 'INVALID_PARAMETER';
  message: '"media.screen" should be true, or the options of getDisplayMedia().'; // and the like for icePolicy, receive, encoding, channels, meta and ringTimeout
}

vapidPublicKey

vapidPublicKey(): Promise<{ VAPIDPublicKey: string }>

subscribeNotification

subscribeNotification(
  endpoint: string,
  keys: {
    p256dh: string;
    auth: string;
  }
): Promise<'SUCCESS: Subscribed to receive notifications.'>

unsubscribeNotification

unsubscribeNotification(
  endpoint: string,
  keys: {
    p256dh: string;
    auth: string;
  }
): Promise<'SUCCESS: Unsubscribed from notifications.'>

pushNotification

pushNotification(
  params: {
    title: string;
    body: string; // title and body together at most 3072 bytes.
  },
  user_ids?: string | string[] // Up to 1000 users. Each gets it on every device they registered. Without it, every registered device of the project gets it.
): Promise<"SUCCESS: Notification sent.">