The SignalWire Client

The SignalWire Client provides access to SignalWire’s services on the browser. It provides methods to handle incoming calls, dial to addresses, and register devices for notifications.

Instantiation

The SignalWire client is instantiated using the SignalWire function.

If you’re including the @signalwire/js dependency as a script in HTML, the SignalWire function is a property of the SignalWire global variable that the script sets:

1 <script type="text/javascript" src="https://cdn.signalwire.com/@signalwire/js"></script>
2 <script>
3   async function main() {
4     const client = await SignalWire.SignalWire({
5       token: "<TOKEN>",
6     });
7   }
8 </script>

If you installed @signalwire/js from npm:

1 import { SignalWire } from "@signalwire/js";
2 
3 async function main() {
4   const client = await SignalWire({
5     token: "<TOKEN>",
6   });
7 }

For React or React Native projects, use the community library:

1 import { useSignalWire } from "@signalwire-community/react";
2 
3 export default function App() {
4   const client = useSignalWire({
5     token: "<TOKEN>",
6   });
7 }

Parameters

token

stringRequired

The access token for the subscriber.

rootElement

HTMLElement

The HTML container element where the SDK will display the video stream.

incomingCallHandlers

IncomingCallHandlers

Callback functions for when a call is received. See IncomingCallHandlers.

userVariables

Record<string, any toc={true}>

Arbitrary variables that are transparent to FreeSWITCH.

You can manage the DOM yourself by not specifying a rootElement here and using the buildVideoElement function instead.

Example

Vanilla JS

React (community)

1 <html>
2   <body>
3     <script type="text/javascript" src="https://cdn.signalwire.com/@signalwire/js"></script>
4 
5     <script>
6       async function main() {
7         const client = await SignalWire.SignalWire({
8           token: "<TOKEN>",
9         });
10 
11         const conversations = await client.conversation.getConversations();
12         console.log(conversations);
13 
14         const addresses = await client.address.getAddresses();
15         console.log(addresses);
16       }
17       main();
18     </script>
19   </body>
20 </html>

Properties

httpHost

string

Returns the URL of the host that the client will use to make HTTP requests (like querying the list of addresses or conversations). Read-only.

1 console.log(client.httpHost());
2 // fabric.signalwire.com

Methods

dial

Dial to an address

online

Go online to receive call invites

offline

Go offline to stop receiving call invites

getSubscriberInfo

Get info about the current subscriber

connect

Connect the WebSocket client

disconnect

Disconnect the WebSocket client

updateToken

Update the auth token

Namespaces

Certain methods and properties are organized into namespaces for clarity. They can be accessed as follows:

1 client.address.getAddresses();
2 client.chat.getMessages();
3 client.conversation.getConversations();

Address

Methods for working with addresses

Chat

Methods for chat functionality

Conversation

Methods for conversations

Type aliases

IncomingCallHandlers

Use this object to assign callback functions which get invoked when a call is received.

Name	Type	Required?	Description
`all`	`(IncomingCallNotification) => void`	Optional	Since push support has been removed, identical to `websocket`
`websocket`	`(IncomingCallNotification) => void`	Optional	Callback for calls received via websocket (overrides `all`)

IncomingCallNotification

The object passed into the IncomingCallHandlers callback with the call description and controls.

Name	Type	Description
`invite`	`object`	-
`invite.details`	IncomingInvite	The details of the invite.
`invite.accept`	`(CallOptions) => Promise<CallFabricRoomSession>`	Invoke this function to accept the incoming call
`invite.reject`	`() => Promise<void>`	Invoke this function to reject the incoming call

IncomingInvite

Name	Type	Description
`source`	`"websocket"`
`callID`	`string`	Unique ID of the incoming call
`sdp`	`string`	Deprecated
`caller_id_name`	`string`	Name of the caller
`caller_id_number`	`string`	ID or number of the caller
`callee_id_name`	`string`	Name of the callee
`callee_id_number`	`string`	ID or number of the callee
`display_direction`	`string`	Direction of the call
`nodeId`	`string`	The node from where the call was received

CallOptions

Name	Type	Required?	Description
`rootElement`	`HTMLElement`	Optional	The HTML container element where the SDK will display the video stream.
`audio`	`boolean \| MediaTrackConstraints`	Optional	Media track constraints for audio. Passing `true` uses browser defaults, and `false` disables audio.
`video`	`boolean \| MediaTrackConstraints`	Optional	Media track constraints for video. Passing `true` uses browser defaults, and `false` disables video.
`disableUdpIceServers`	`boolean`	Optional	Disables the ICE UDP transport policy.
`userVariables`	`Record<string, any>`	Optional	Arbitrary variables that are transparent to FreeSWITCH.

MediaStreamConstraints

Name	Type	Required?	Description
`audio`	`boolean \| MediaTrackConstraints`	Optional	Media track constraints for audio. Passing `true` uses browser defaults, and `false` disables audio.
`video`	`boolean \| MediaTrackConstraints`	Optional	Media track constraints for video. Passing `true` uses browser defaults, and `false` disables video.
`peerIdentity`	`string`	Optional	Peer identity.
`preferCurrentTab`	`boolean`	Optional	Whether to prefer current tab for the call.

CallFabricRoomSession

Extends RoomSession.

Name	Type	Description
`start`	`() => void`	Starts the call.
`answer`	`boolean \| MediaTrackConstraints`	Answers the call (only works if the `CallFabricRoomSession` was a result of an incoming call).
`hangup`	`(id?) => void`	Ends the ongoing call by default. If the id of an `RTCPeer` is passed, hangs up that `RTCPeer`.

The SignalWire Client provides access to SignalWire’s services on the browser. It provides methods to handle incoming calls, dial to addresses, and register devices for notifications.

Instantiation

The SignalWire client is instantiated using the SignalWire function.

If you’re including the @signalwire/js dependency as a script in HTML, the SignalWire function is a property of the SignalWire global variable that the script sets:

1 <script type="text/javascript" src="https://cdn.signalwire.com/@signalwire/js"></script>
2 <script>
3   async function main() {
4     const client = await SignalWire.SignalWire({
5       token: "<TOKEN>",
6     });
7   }
8 </script>

If you installed @signalwire/js from npm:

1 import { SignalWire } from "@signalwire/js";
2 
3 async function main() {
4   const client = await SignalWire({
5     token: "<TOKEN>",
6   });
7 }

For React or React Native projects, use the community library:

1 import { useSignalWire } from "@signalwire-community/react";
2 
3 export default function App() {
4   const client = useSignalWire({
5     token: "<TOKEN>",
6   });
7 }

Parameters

token

stringRequired

The access token for the subscriber.

rootElement

HTMLElement

The HTML container element where the SDK will display the video stream.

incomingCallHandlers

IncomingCallHandlers

Callback functions for when a call is received. See IncomingCallHandlers.

userVariables

Record<string, any toc={true}>

Arbitrary variables that are transparent to FreeSWITCH.

You can manage the DOM yourself by not specifying a rootElement here and using the buildVideoElement function instead.

Example

Vanilla JS

React (community)

1 <html>
2   <body>
3     <script type="text/javascript" src="https://cdn.signalwire.com/@signalwire/js"></script>
4 
5     <script>
6       async function main() {
7         const client = await SignalWire.SignalWire({
8           token: "<TOKEN>",
9         });
10 
11         const conversations = await client.conversation.getConversations();
12         console.log(conversations);
13 
14         const addresses = await client.address.getAddresses();
15         console.log(addresses);
16       }
17       main();
18     </script>
19   </body>
20 </html>

Properties

httpHost

string

Returns the URL of the host that the client will use to make HTTP requests (like querying the list of addresses or conversations). Read-only.

1 console.log(client.httpHost());
2 // fabric.signalwire.com

Methods

dial

Dial to an address

online

Go online to receive call invites

offline

Go offline to stop receiving call invites

getSubscriberInfo

Get info about the current subscriber

connect

Connect the WebSocket client

disconnect

Disconnect the WebSocket client

updateToken

Update the auth token

Namespaces

Certain methods and properties are organized into namespaces for clarity. They can be accessed as follows:

1 client.address.getAddresses();
2 client.chat.getMessages();
3 client.conversation.getConversations();

Address

Methods for working with addresses

Chat

Methods for chat functionality

Conversation

Methods for conversations

Type aliases

IncomingCallHandlers

Use this object to assign callback functions which get invoked when a call is received.

Name	Type	Required?	Description
`all`	`(IncomingCallNotification) => void`	Optional	Since push support has been removed, identical to `websocket`
`websocket`	`(IncomingCallNotification) => void`	Optional	Callback for calls received via websocket (overrides `all`)

IncomingCallNotification

The object passed into the IncomingCallHandlers callback with the call description and controls.

Name	Type	Description
`invite`	`object`	-
`invite.details`	IncomingInvite	The details of the invite.
`invite.accept`	`(CallOptions) => Promise<CallFabricRoomSession>`	Invoke this function to accept the incoming call
`invite.reject`	`() => Promise<void>`	Invoke this function to reject the incoming call

IncomingInvite

Name	Type	Description
`source`	`"websocket"`
`callID`	`string`	Unique ID of the incoming call
`sdp`	`string`	Deprecated
`caller_id_name`	`string`	Name of the caller
`caller_id_number`	`string`	ID or number of the caller
`callee_id_name`	`string`	Name of the callee
`callee_id_number`	`string`	ID or number of the callee
`display_direction`	`string`	Direction of the call
`nodeId`	`string`	The node from where the call was received

CallOptions

Name	Type	Required?	Description
`rootElement`	`HTMLElement`	Optional	The HTML container element where the SDK will display the video stream.
`audio`	`boolean \| MediaTrackConstraints`	Optional	Media track constraints for audio. Passing `true` uses browser defaults, and `false` disables audio.
`video`	`boolean \| MediaTrackConstraints`	Optional	Media track constraints for video. Passing `true` uses browser defaults, and `false` disables video.
`disableUdpIceServers`	`boolean`	Optional	Disables the ICE UDP transport policy.
`userVariables`	`Record<string, any>`	Optional	Arbitrary variables that are transparent to FreeSWITCH.

MediaStreamConstraints

Name	Type	Required?	Description
`audio`	`boolean \| MediaTrackConstraints`	Optional	Media track constraints for audio. Passing `true` uses browser defaults, and `false` disables audio.
`video`	`boolean \| MediaTrackConstraints`	Optional	Media track constraints for video. Passing `true` uses browser defaults, and `false` disables video.
`peerIdentity`	`string`	Optional	Peer identity.
`preferCurrentTab`	`boolean`	Optional	Whether to prefer current tab for the call.

CallFabricRoomSession

Extends RoomSession.

Name	Type	Description
`start`	`() => void`	Starts the call.
`answer`	`boolean \| MediaTrackConstraints`	Answers the call (only works if the `CallFabricRoomSession` was a result of an incoming call).
`hangup`	`(id?) => void`	Ends the ongoing call by default. If the id of an `RTCPeer` is passed, hangs up that `RTCPeer`.

1	<script type="text/javascript" src="https://cdn.signalwire.com/@signalwire/js"></script>
2	<script>
3	async function main() {
4	const client = await SignalWire.SignalWire({
5	token: "<TOKEN>",
6	});
7	}
8	</script>

1	import { SignalWire } from "@signalwire/js";
2
3	async function main() {
4	const client = await SignalWire({
5	token: "<TOKEN>",
6	});
7	}

1	import { useSignalWire } from "@signalwire-community/react";
2
3	export default function App() {
4	const client = useSignalWire({
5	token: "<TOKEN>",
6	});
7	}

1	<html>
2	<body>
3	<script type="text/javascript" src="https://cdn.signalwire.com/@signalwire/js"></script>
4
5	<script>
6	async function main() {
7	const client = await SignalWire.SignalWire({
8	token: "<TOKEN>",
9	});
10
11	const conversations = await client.conversation.getConversations();
12	console.log(conversations);
13
14	const addresses = await client.address.getAddresses();
15	console.log(addresses);
16	}
17	main();
18	</script>
19	</body>
20	</html>

1	client.address.getAddresses();
2	client.chat.getMessages();
3	client.conversation.getConversations();