Skip to main content

Client

You can use instances of this class to initiate or receive calls. Please see Events for the full list of events you can subscribe to.

Examples

The following example answers any call in the "office" context.

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

const client = new Voice.Client({
project: "<project-id>",
token: "<api-token>",
contexts: ["office"],
});

client.on("call.received", async (call) => {
console.log("Got call", call.from, call.to);

try {
await call.answer();
console.log("Inbound call answered");
} catch (error) {
console.error("Error answering inbound call", error);
}
});

The following example initiates a new call.

const client = new Voice.Client({
project: "<project-id>",
token: "<api-token>",
contexts: ["office"],
});

try {
const call = await client.dialPhone({
from: "+YYYYYYYYYY",
to: "+XXXXXXXXXX",
timeout: 30,
});
} catch (e) {
console.log("Call not answered.");
}

Constructors

constructor

new Client(opts)

Parameters

NameTypeDescription
optsObject-
opts.contextsstring[]SignalWire contexts, e.g. ['home', 'office'].
opts.projectstringSignalWire project id, e.g. a10d8a9f-2166-4e82-56ff-118bc3a4840f.
opts.tokenstringSignalWire project token, e.g. PT9e5660c101cd140a1c93a0197640a369cf5f16975a0079c9.

Methods

dial

dial(dialer): Promise<Call>

Makes an outbound Call and waits until it has been answered or hung up. This is an advanced method that lets you call multiple devices in parallel or series: for simpler use cases, see dialPhone and dialSip.

With this method you can specify a configuration of devices to call in series and/or in parallel: as soon as one device answers the call, the returned promise is resolved. You specify a configuration through a VoiceDeviceBuilder object.

Parameters

NameTypeDescription
dialerVoiceDeviceBuilderThe Dialer specifying the devices to call.

Returns

Promise<Call>

A call object.

Example

Calls a phone number. If the number doesn't answer within 30 seconds, calls two different SIP endpoints in parallel.

const devices = new Voice.DeviceBuilder()
.add(
Voice.DeviceBuilder.Phone({ from: "+XXXXXX", to: "+YYYYYY", timeout: 30 })
)
.add([
Voice.DeviceBuilder.Sip({ from: "sip:aaa@bbb.cc", to: "sip:xxx@yyy.zz" }),
Voice.DeviceBuilder.Sip({ from: "sip:aaa@bbb.cc", to: "sip:ppp@qqq.rr" }),
]);

try {
const call = await client.dial(devices);
console.log("Call answered");
} catch (e) {
console.log("Call not answered");
}

dialPhone

dialPhone(params): Promise<Call>

Makes an outbound call to a PSTN number.

Parameters

NameTypeDescription
paramsObject-
params.from?stringThe party the call is coming from. Must be a SignalWire number or SIP endpoint that you own.
params.timeout?numberThe time, in seconds, the call will ring before it is considered unanswered.
params.tostringThe party you are attempting to call.

Returns

Promise<Call>

A call object.

Example

try {
const call = await client.dialPhone({
from: "+YYYYYYYYYY",
to: "+XXXXXXXXXX",
timeout: 30,
});
} catch (e) {
console.log("Call not answered.");
}

dialSip

dialSip(params): Promise<Call>

Makes an outbound call to a SIP endpoint.

Parameters

NameTypeDescription
paramsObject-
params.codecs?SipCodec[]Optional array of desired codecs in order of preference. Supported values are PCMU, PCMA, OPUS, G729, G722, VP8, H264. Default is parent leg codec(s).
params.fromstringThe party the call is coming from. Must be a SignalWire number or SIP endpoint that you own.
params.headers?SipHeader[]Array of SipHeader objects. Must be X- headers only, see example below.
params.timeout?numberThe time, in seconds, the call will ring before it is considered unanswered.
params.tostringThe party you are attempting to call.
params.webrtcMedia?booleanIf true, WebRTC media is negotiated. Default is parent leg setting.

Returns

Promise<Call>

A call object.

Example

try {
const call = await client.dialSip({
from: "sip:xxx@yyy.zz",
to: "sip:ppp@qqq.rr",
timeout: 30,
headers: [
{ name: "X-SomeKeyA", value: "SomeValueA" },
{ name: "X-SomeKeyB", value: "SomeValueB" },
],
});
} catch (e) {
console.log("Call not answered.");
}

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();

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.

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.

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.

Events

call.received

call.received(call)

A call has been received. You can use the provided Call object to answer.

Parameters

NameType
callCall

playback.ended

playback.ended(playback)

A playback ended.

Parameters

NameTypeDescription
playbackCallPlaybackA playback object.

playback.started

playback.started(playback)

A playback has started.

Parameters

NameTypeDescription
playbackCallPlaybackA playback object.

playback.updated

playback.updated(playback)

The state of a playback changed.

Parameters

NameTypeDescription
playbackCallPlaybackA playback object.

prompt.ended

prompt.ended(prompt)

A prompt has ended.

Parameters

NameTypeDescription
promptCallPromptA prompt object.

prompt.failed

prompt.failed(prompt)

A prompt has failed.

Parameters

NameTypeDescription
promptCallPromptA prompt object.

prompt.started

prompt.started(prompt)

A prompt started.

Parameters

NameTypeDescription
promptCallPromptA prompt object.

prompt.updated

prompt.updated(prompt)

The state of a prompt changed.

Parameters

NameTypeDescription
promptCallPromptA prompt object.

recording.ended

recording.ended(recording)

A recording ended.

Parameters

NameTypeDescription
recordingCallRecordingA recording object.

recording.failed

recording.failed(recording)

A recording failed.

Parameters

NameTypeDescription
recordingCallRecordingA recording object.

recording.started

recording.started(recording)

A recording started.

Parameters

NameTypeDescription
recordingCallRecordingA recording object.

recording.updated

recording.updated(recording)

The state of a recording changed.

Parameters

NameTypeDescription
recordingCallRecordingA recording object.

tap.ended

tap.ended(tap)

A tap ended.

Parameters

NameTypeDescription
tapCallTapA tap object.

tap.started

tap.started(tap)

A tap started.

Parameters

NameTypeDescription
tapCallTapA tap object.