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

Name	Type	Description
opts	Object	-
opts.topics	string[]	SignalWire topics, e.g. ['home', 'office']. Previously known as "context".
opts.project	string	SignalWire project id, e.g. a10d8a9f-2166-4e82-56ff-118bc3a4840f.
opts.token	string	SignalWire project token, e.g. PT9e5660c101cd140a1c93a0197640a369cf5f16975a0079c9.
opts.debug?	Object	-
opts.debug.logWsTraffic?	boolean	If 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

Name	Type	Description
dialer	VoiceDeviceBuilder	The 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

Name	Type	Description
params	Object	-
params.from?	string	The party the call is coming from. Must be a SignalWire number or SIP endpoint that you own.
params.maxPricePerMinute?	number	The 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?	number	The time, in seconds, the call will ring before it is considered unanswered.
params.to	string	The 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

Name	Type	Description
params	Object	-
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.from	string	The 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?	number	The 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?	number	The time, in seconds, the call will ring before it is considered unanswered.
params.to	string	The party you are attempting to call.
params.webrtcMedia?	boolean	If true, WebRTC media is negotiated. Default is parent leg setting.
params.sessionTimeout?	number	Non-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

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.

---

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.

---

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.

Events

call.received

• call.received(call)

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

Parameters

Name	Type
call	Call