Skip to main content

Chat.Client

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

Example usage:

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

const chatClient = new Chat.Client({
token: "<your_chat_token>", // get this from the REST APIs
});

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

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

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

Constructors

constructor

new Client(chatOptions)

Creates a new Chat client.

Parameters

NameTypeDescription
chatOptionsObject-
chatOptions.tokenstringSignalWire Chat token that can be obtained from the REST APIs.

Example

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

const chatClient = new Chat.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 chatClient = new Chat.Client({
token: "<your chat token>",
});

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

getMemberState

getMemberState(params): Promise<{ channels: Record<string, ChatChannelState> }>

Returns the states of a member in the specified channels.

Parameters

NameTypeDescription
paramsObject-
params.channels?string | string[]Channels for which to get the state.
params.memberIdstringId of the member for which to get the state.

Returns

Promise<{ channels: Record<string, ChatChannelState> }>

Example

const s = await chatClient.getMemberState({
channels: ["chan1", "chan2"],
memberId: "my-member-id",
});

s.channels.length; // 2
s.channels.chan1.state; // the state object for chan1

getMembers

getMembers(params): Promise<{ members: ChatMemberEntity[] }> - See ChatMemberEntity documentation for more details.

Returns the list of members in the given channel.

Parameters

NameTypeDescription
paramsObject-
params.channelstringThe channel for which to get the list of members.

Returns

Promise<{ members: ChatMemberEntity[] }> - See ChatMemberEntity documentation for more details.

Example

const m = await chatClient.getMembers({ channel: "my-channel" });

m.members.length; // 7
m.members[0]; // { id: ..., channel: ..., state: ... }

getMessages

getMessages(params): Promise<{ cursor: PagingCursor; messages: ChatMessageEntity[] }>

See PagingCursor documentation and ChatMessageEntity documentation for more details.

Returns the list of messages that were sent to the specified channel.

Parameters

NameTypeDescription
paramsObject-
params.channelstringChannel for which to retrieve the messages.
params.cursor?PagingCursorCursor for pagination.

Returns

Promise<{ cursor: PagingCursor; messages: ChatMessageEntity[] }>

See PagingCursor documentation and ChatMessageEntity documentation for more details.

Example

const m = await chatClient.getMessages({ channel: "chan1" });

m.messages.length; // 23
m.messages[0]; // the most recent message
m.messages[0].member; // the sender
m.messages[0].content; // the content
m.messages[0].meta; // the metadata (if any)

m.cursor.next; // if not null, there are more messages.

// Get the next page using the cursor
const next = await chatClient.getMessages({
channel: "chan1",
cursor: {
after: m.cursor.after,
},
});

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 or value.
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 chatClient.publish({
channel: "my-channel",
content: "Hello, world."
});

Publishing a message as an object:

await chatClient.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.

setMemberState

setMemberState(params): Promise<void>

Sets a state object for a member, for the specified channels. The previous state object will be completely replaced.

Parameters

NameTypeDescription
paramsObject-
params.channelsstring | string[]Channels for which to set the state.
params.memberIdstringId of the member to affect. If not provided, defaults to the current member.
params.stateRecord<any, any>The state to set. There are no requirements on the content of the state.

Returns

Promise<void>

Example

await chatClient.setMemberState({
channels: ["chan1", "chan2"],
state: {
online: true,
typing: false,
},
});

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 chatClient = new Chat.Client({
token: "<your chat token>",
});

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

await chatClient.subscribe("my-channel");
await chatClient.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 chatClient.unsubscribe("my-channel");
await chatClient.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 chatClient = new Chat.Client({
token: '<your chat token>'
})

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

await chatClient.updateToken(newToken)
})

Events

member.joined

member.joined(member)

A new member joined the chat.

Parameters

NameType
memberChatMember

member.left

member.left(member)

A member left the chat.

Parameters

NameType
memberChatMember

member.updated

member.updated(member)

A member updated its state.

Parameters

NameType
memberChatMember

message

message(message)

A new message has been received.

Parameters

NameType
messageChatMessage

session.expiring

session.expiring()

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


Type Aliases

PaginationCursor

This is a utility object that aids in pagination. It is specifically used in conjunction with the getMessages method.

Properties

  • Readonly after?: string

This property signifies the cursor for the subsequent page.

  • Readonly before?: string

This property signifies the cursor for the preceding page.