Skip to main content

PubSub.Client

You can use the Client object to build a messaging system into the browser.

Example usage:

import { PubSub } from "@signalwire/js";

const pubSubClient = new PubSub.Client({
token: "<your chat token>", // get this from the REST APIs
});

await pubSubClient.subscribe(["mychannel1", "mychannel2"]);

pubSubClient.on("message", (message) => {
console.log("Received", message.content,
"on", message.channel,
"at", message.publishedAt);
});

await pubSubClient.publish({
channel: "mychannel1",
content: "hello world",
});

Constructors​

constructor​

• new Client(pubSubOptions)

Creates a new PubSub client.

Parameters​

NameTypeDescription
pubSubOptionsObject-
pubSubOptions.tokenstringSignalWire Chat token that can be obtained from the REST APIs.

Example​

import { PubSub } from "@signalwire/js";

const pubSubClient = new PubSub.Client({
token: "<your chat token>"
});

Methods​

disconnect​

â–¸ disconnect(): void

Disconnects this client. The client will stop receiving events and you will need to create a new instance if you want to use it again.

Returns​

void

Example​

client.disconnect();

getAllowedChannels​

â–¸ getAllowedChannels(): Promise<Object>

Returns the channels that the current token allows you to subscribe to.

Returns​

Promise<Object>

An object whose keys are the channel names, and whose values are the permissions. For example:

{
"my-channel-1": { "read": true, "write": false },
"my-channel-2": { "read": true, "write": true },
}

Examples​

const pubSubClient = new PubSub.Client({
token: "<your chat token>",
});

const channels = await pubSubClient.getAllowedChannels();
console.log(channels);

off​

â–¸ off(event, fn?)

Remove an event handler.

Parameters​

NameTypeDescription
eventstringName of the event. See Events for the list of available events.
fn?FunctionAn event handler which had been previously attached.

on​

â–¸ on(event, fn)

Attaches an event handler to the specified event.

Parameters​

NameTypeDescription
eventstringName of the event. See Events for the list of available events.
fnFunctionAn event handler.

Example​

In the below example, we are listening for the call.state event and logging the current call state to the console. This means this will be triggered every time the call state changes.

call.on("call.state", (call) => {
console.log("call state changed:", call.state);
});

once​

â–¸ once(event, fn)

Attaches an event handler to the specified event. The handler will fire only once.

Parameters​

NameTypeDescription
eventstringName of the event. See Events for the list of available events.
fnFunctionAn event handler.

publish​

â–¸ publish(params): Promise<void>

Publish a message into the specified channel.

Parameters​

NameTypeDescription
paramsObject-
params.channelstringChannel in which to send the message.
params.contentanyThe message to send. This can be any JSON-serializable object.
params.meta?Record<any, any>Metadata associated with the message. There are no requirements on the content of metadata.

Returns​

Promise<void>

Examples​

Publishing a message as a string:

await pubSub.publish({
channel: "my-channel",
content: "Hello, world."
});

Publishing a message as an object:

await pubSub.publish({
channel: "my-channel",
content: {
field_one: "value_one",
field_two: "value_two"
},
});

removeAllListeners​

â–¸ removeAllListeners(event?)

Detaches all event listeners for the specified event.

Parameters​

NameTypeDescription
event?stringName of the event (leave this undefined to detach listeners for all events). See Events for the list of available events.

subscribe​

â–¸ subscribe(channels): Promise<void>

List of channels for which you want to receive messages. You can only subscribe to those channels for which your token has read permission.

Note that the subscribe function is idempotent, and calling it again with a different set of channels will not unsubscribe you from the old ones. To unsubscribe, use unsubscribe.

Parameters​

NameTypeDescription
channelsstring | string[]The channels to subscribe to, either in the form of a string (for one channel) or an array of strings.

Returns​

Promise<void>

Example​

const pubSub = new PubSub.Client({
token: "<your chat token>"
});

pubSub.on("message", (m) => console.log(m));

await pubSub.subscribe("my-channel");
await pubSub.subscribe(["chan-2", "chan-3"]);

unsubscribe​

â–¸ unsubscribe(channels): Promise<void>

List of channels from which you want to unsubscribe.

Parameters​

NameTypeDescription
channelsstring | string[]The channels to unsubscribe from, either in the form of a string (for one channel) or an array of strings.

Returns​

Promise<void>

Example​

await pubSub.unsubscribe("my-channel");
await pubSub.unsubscribe(["chan-2", "chan-3"]);

updateToken​

â–¸ updateToken(token): Promise<void>

Replaces the token used by the client with a new one. You can use this method to replace the token when, for example, it is expiring, in order to keep the session alive.

The new token can contain different channels from the previous one. In that case, you will need to subscribe to the new channels if you want to receive messages for those. Channels that were in the previous token but are not in the new one will get unsubscribed automatically.

Parameters​

NameTypeDescription
tokenstringThe new token.

Returns​

Promise<void>

Example​

const pubSubClient = new PubSub.Client({
token: '<your chat token>'
})

pubSubClient.on('session.expiring', async () => {
const newToken = await fetchNewToken(..)

await pubSubClient.updateToken(newToken)
})

Events​

message​

• message(message)

A new message has been received.

Parameters​

NameType
messagePubSubMessage<PubSubMessageContract\>

session.expiring​

• session.expiring()

The session is going to expire. Use the updateToken method to refresh your token.