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" topic.

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

const client = new Voice.Client({
  project: "<project-id>",
  token: "<api-token>",
  topics: ["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>",
  topics: ["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.topicsstring[]SignalWire topics, e.g. ['home', 'office']. Previously known as "context".
opts.projectstringSignalWire project id, e.g. a10d8a9f-2166-4e82-56ff-118bc3a4840f.
opts.tokenstringSignalWire project token, e.g. PT9e5660c101cd140a1c93a0197640a369cf5f16975a0079c9.
opts.debug?Object-
opts.debug.logWsTraffic?booleanIf true, logs all WebSocket traffic. Default is false.

Methods​

dial​

â–¸ dial(dialer): Promise<Call> - See Call for more details.

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> - See Call for more details.

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> - See Call for more details.

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.maxPricePerMinute?numberThe maximum price in USD acceptable for the call to be created. If the rate for the call is greater than this value, the call will not be created. If not set, all calls will be created. Price can have a maximum of four decimal places, i.e. 0.0075.
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> - See Call for more details.

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> - See Call for more details.

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.maxPricePerMinute?numberThe maximum price in USD acceptable for the call to be created. If the rate for the call is greater than this value, the call will not be created. If not set, all calls will be created. Price can have a maximum of four decimal places, i.e. 0.0075.
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.
params.sessionTimeout?numberNon-negative value, in seconds, to use for the SIP Session-Expires header. If 0 or unset, SignalWire will pick the default (typically 600).

Returns​

Promise<Call> - See Call for more details.

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.

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.

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