Voice

DeviceBuilder

View as Markdown

A DeviceBuilder object allows you to specify a set of devices which should be dialed in sequence or parallel. You can then pass the device plan to the methods that support it, for example Call.connect.

Example

Creates a plan which specifies to dial a SIP endpoint. If there is no answer within 30 seconds, calls two phone numbers in parallel (as indicated by the array syntax). As soon as one of the two answers, the operation is considered successful.

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const devices = new Voice.DeviceBuilder()
6  .add(
7    Voice.DeviceBuilder.Sip({
8      from: "sip:user1@domain.com",
9      to: "sip:user2@domain.com",
10      timeout: 30,
11    })
12  )
13  .add([
14    Voice.DeviceBuilder.Phone({ to: "+1yyyyyyyyyy", from: "+1xxxxxxxxxx", timeout: 30 }),
15    Voice.DeviceBuilder.Phone({ to: "+1zzzzzzzzzz", from: "+1xxxxxxxxxx", timeout: 30 }),
16  ]);
17
18const call = await client.voice.dial(devices);
19console.log("Call answered:", call.id);

Constructors

constructor

• new DeviceBuilder()

Instantiates an empty DeviceBuilder. Use the add method to add devices to this DeviceBuilder.

Example

1import { Voice } from "@signalwire/realtime-api";
2
3const devices = new Voice.DeviceBuilder();

Properties

devices
NestedArray<Object>

The list of devices that have been added to this DeviceBuilder.

Methods

add

▸ add(device): DeviceBuilder

Adds the specified device (or set of devices) in series to this DeviceBuilder. When you add a device in series, a call to that device will be made only if none of the previously added devices answer the call.

You can pass either a device (Phone or Sip) or an array of devices.

  • Passing a single device will add that device in series to the sequence.
  • Passing an array of devices will add those devices in series to the previous ones, but among themselves they will be called in parallel.

Parameters

device
object | object[]Required

A single device or an array of devices. See Phone and Sip.

Returns

DeviceBuilder

Example

Adding two devices in series. If "+1xxxxxxxxxx" doesn’t answer within 30 seconds, "+1yyyyyyyyyy" will be called.

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const devices = new Voice.DeviceBuilder()
6  .add(Voice.DeviceBuilder.Phone({ to: "+1xxxxxxxxxx", from: "+1aaaaaaaaaa", timeout: 30 }))
7  .add(Voice.DeviceBuilder.Phone({ to: "+1yyyyyyyyyy", from: "+1aaaaaaaaaa", timeout: 30 }));
8
9const call = await client.voice.dial(devices);

Adding two devices in parallel. Both will ring simultaneously. As soon as either "+1xxxxxxxxxx" or "+1yyyyyyyyyy" answers, the other stops ringing.

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const devices = new Voice.DeviceBuilder().add([
6  Voice.DeviceBuilder.Phone({ to: "+1xxxxxxxxxx", from: "+1aaaaaaaaaa", timeout: 30 }),
7  Voice.DeviceBuilder.Phone({ to: "+1yyyyyyyyyy", from: "+1bbbbbbbbbb", timeout: 30 }),
8]);
9
10const call = await client.voice.dial(devices);

Mixing series and parallel. First calls the SIP device. If it doesn’t answer, calls "+1yyyyyyyyyy" and "+1zzzzzzzzzz" simultaneously.

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const devices = new Voice.DeviceBuilder()
6  .add(
7    Voice.DeviceBuilder.Sip({
8      from: "sip:user1@domain.com",
9      to: "sip:user2@domain.com",
10      timeout: 30,
11    })
12  )
13  .add([
14    Voice.DeviceBuilder.Phone({ to: "+1yyyyyyyyyy", from: "+1aaaaaaaaaa", timeout: 30 }),
15    Voice.DeviceBuilder.Phone({ to: "+1zzzzzzzzzz", from: "+1bbbbbbbbbb", timeout: 30 }),
16  ]);
17
18const call = await client.voice.dial(devices);

Phone

▸ Static Phone(params): VoiceCallPhoneParams

Represents the configuration to call a phone device.

Parameters

params
objectRequired

Object containing the parameters of the method.

to
stringRequired

Number to call, in E.164 format.

from
stringRequired

SignalWire number to use to initiate the call, in E.164 format.

timeout
numberDefaults to 30

Time to wait for the call to be answered, in seconds.

callStateUrl
string

Optional webhook URL to which SignalWire will send call status change notifications. See the payload specifications under CallState.

callStateEvents
string[]Defaults to ["ended"]

An optional array of event names to be notified about. Allowed values are created, ringing, answered, and ended.

maxPricePerMinute
number

The optional 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.

Returns

VoiceCallPhoneParams - A device configuration object to pass to DeviceBuilder.add().

Example

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const devices = new Voice.DeviceBuilder()
6  .add(Voice.DeviceBuilder.Phone({
7    to: "+1yyyyyyyyyy",
8    from: "+1xxxxxxxxxx",
9    timeout: 30,
10    callStateUrl: "https://example.com/call-state-webhook",
11    callStateEvents: ["created", "ringing", "answered", "ended"],
12    maxPricePerMinute: 0.50
13  }));
14
15const call = await client.voice.dial(devices);

Sip

▸ Static Sip(params): VoiceCallSipParams

Represents the configuration to call a SIP device.

Parameters

params
objectRequired

Object containing the parameters of the method.

to
stringRequired

SIP endpoint URI to call.

from
stringRequired

SIP endpoint URI to use to initiate the call.

timeout
numberDefaults to 30

Time to wait for the call to be answered, in seconds.

codecs
SipCodec[]

Optional array of desired codecs in order of preference. See SipCodec.

headers
SipHeader[]

Optional array of headers. Must be X- headers only. See SipHeader.

callStateUrl
string

Optional webhook URL to which SignalWire will send call status change notifications. See the payload specifications under CallState.

callStateEvents
string[]Defaults to ["ended"]

An optional array of event names to be notified about. Allowed values are created, ringing, answered, and ended.

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.

Returns

VoiceCallSipParams - A device configuration object to pass to DeviceBuilder.add().

Example

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const devices = new Voice.DeviceBuilder()
6  .add(Voice.DeviceBuilder.Sip({
7    from: "sip:user1@domain.com",
8    to: "sip:user2@domain.com",
9    timeout: 30,
10    codecs: ["PCMU", "PCMA", "OPUS"],
11    headers: [
12      { name: "X-Custom-Header", value: "custom-value" }
13    ],
14    callStateUrl: "https://example.com/call-state-webhook",
15    callStateEvents: ["created", "ringing", "answered", "ended"],
16    maxPricePerMinute: 0.50
17  }));
18
19const call = await client.voice.dial(devices);