Client

You can use instances of this class to control the chat and subscribe to its events.

Example

const chatClient = new Chat.Client({
  project: "<project-id>",
  token: "<api-token>",
});

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

Name	Type	Description
chatOptions	Object	-
chatOptions.project	string	SignalWire project id, e.g. a10d8a9f-2166-4e82-56ff-118bc3a4840f
chatOptions.token	string	SignalWire API token
chatOptions.debug?	Object	-
chatOptions.debug.logWsTraffic?	boolean	If true, logs all WebSocket traffic. Default is false.

Example

import { Chat } from "@signalwire/realtime-api";

const chatClient = new Chat.Client({
  project: "<project-id>",
  token: "<api-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();

---

getMemberState

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

Returns the states of a member in the specified channels.

Parameters

Name	Type	Description
params	Object	-
params.channels?	string | string[]	Channels for which to get the state.
params.memberId	string	Id 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 for more details.

Returns the list of members in the given channel.

Parameters

Name	Type	Description
params	Object	-
params.channel	string	The channel for which to get the list of members.

Returns

Promise<{ members: ChatMemberEntity[] }> - See ChatMemberEntity 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: PaginationCursor ; messages: ChatMessageEntity[] }> - See ChatMessageEntity for more details.

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

Parameters

Name	Type	Description
params	Object	-
params.channel	string	Channel for which to retrieve the messages.
params.cursor?	PaginationCursor	Cursor for pagination.

Returns

Promise<{ cursor: PaginationCursor ; messages: ChatMessageEntity[] }> - See ChatMessageEntity 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

Name	Type	Description
event	string	Name of the event. See Events for the list of available events.
fn?	Function	An event handler which had been previously attached.

---

on

▸ on(event, fn)

Attaches an event handler to the specified event.

Parameters

Name	Type	Description
event	string	Name of the event. See Events for the list of available events.
fn	Function	An 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

Name	Type	Description
event	string	Name of the event. See Events for the list of available events.
fn	Function	An event handler.

---

publish

▸ publish(params): Promise<void>

Publish a message into the specified channel.

Parameters

Name	Type	Description
params	Object	-
params.channel	string	Channel in which to send the message.
params.content	any	The 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

Name	Type	Description
event?	string	Name 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

Name	Type	Description
params	Object	-
params.channels	string | string[]	Channels for which to set the state.
params.memberId	string	Id of the member to affect.
params.state	Record<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.

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

Name	Type	Description
channels	string | 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({
  project: "<project-id>",
  token: "<api-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

Name	Type	Description
channels	string | 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"]);

Events

member.joined

• member.joined(member)

A new member joined the chat.

Parameters

Name	Type
member	ChatMember

---

member.left

• member.left(member)

A member left the chat.

Parameters

Name	Type
member	ChatMember

---

member.updated

• member.updated(member)

A member updated its state.

Parameters

Name	Type
member	ChatMember

---

message

• message(message)

A new message has been received.

Parameters

Name	Type
message	ChatMessage

Type Aliases

ChatMemberEntity

An object representing a Chat Member with only the state properties of ChatMember.

Properties

• Readonly channel: string

The channel of this member.

• Readonly id: string

The id of this member.

• Readonly state: Record<any, any>

The state of this member.

ChatMessageEntity

An object representing a Chat Message with only the state properties of ChatMessage.

Properties

• Readonly content: any

The content of this message.

• Readonly id: string

The id. of this message

• Readonly member: ChatMember

The member which sent this message.

• Readonly meta?: any

Any metadata associated with this message.

• Readonly publishedAt: Date

The date and time at which this message was published.