Voice.DeviceBuilder

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.

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const devices = new Voice.DeviceBuilder()
  .add(
    Voice.DeviceBuilder.Sip({
      from: "sip:user1@domain.com",
      to: "sip:user2@domain.com",
      timeout: 30,
    })
  )
  .add([
    Voice.DeviceBuilder.Phone({ to: "+1yyyyyyyyyy", from: "+1xxxxxxxxxx", timeout: 30 }),
    Voice.DeviceBuilder.Phone({ to: "+1zzzzzzzzzz", from: "+1xxxxxxxxxx", timeout: 30 }),
  ]);

const call = await client.voice.dial(devices);
console.log("Call answered:", call.id);

Constructors

constructor

• new DeviceBuilder()

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

Example

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

const 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.

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const devices = new Voice.DeviceBuilder()
  .add(Voice.DeviceBuilder.Phone({ to: "+1xxxxxxxxxx", from: "+1aaaaaaaaaa", timeout: 30 }))
  .add(Voice.DeviceBuilder.Phone({ to: "+1yyyyyyyyyy", from: "+1aaaaaaaaaa", timeout: 30 }));

const 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.

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const devices = new Voice.DeviceBuilder().add([
  Voice.DeviceBuilder.Phone({ to: "+1xxxxxxxxxx", from: "+1aaaaaaaaaa", timeout: 30 }),
  Voice.DeviceBuilder.Phone({ to: "+1yyyyyyyyyy", from: "+1bbbbbbbbbb", timeout: 30 }),
]);

const 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.

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const devices = new Voice.DeviceBuilder()
  .add(
    Voice.DeviceBuilder.Sip({
      from: "sip:user1@domain.com",
      to: "sip:user2@domain.com",
      timeout: 30,
    })
  )
  .add([
    Voice.DeviceBuilder.Phone({ to: "+1yyyyyyyyyy", from: "+1aaaaaaaaaa", timeout: 30 }),
    Voice.DeviceBuilder.Phone({ to: "+1zzzzzzzzzz", from: "+1bbbbbbbbbb", timeout: 30 }),
  ]);

const 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.

params.to

stringrequired

Number to call, in E.164 format.

params.from

stringrequired

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

params.timeout

number

Default: 30

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

params.callStateUrl

string

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

params.callStateEvents

string[]

Default: ["ended"]

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

params.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

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const devices = new Voice.DeviceBuilder()
  .add(Voice.DeviceBuilder.Phone({
    to: "+1yyyyyyyyyy",
    from: "+1xxxxxxxxxx",
    timeout: 30,
    callStateUrl: "https://example.com/call-state-webhook",
    callStateEvents: ["created", "ringing", "answered", "ended"],
    maxPricePerMinute: 0.50
  }));

const 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.

params.to

stringrequired

SIP endpoint URI to call.

params.from

stringrequired

SIP endpoint URI to use to initiate the call.

params.timeout

number

Default: 30

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

params.codecs

SipCodec[]

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

params.headers

SipHeader[]

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

params.callStateUrl

string

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

params.callStateEvents

string[]

Default: ["ended"]

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

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.

Returns

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

Example

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const devices = new Voice.DeviceBuilder()
  .add(Voice.DeviceBuilder.Sip({
    from: "sip:user1@domain.com",
    to: "sip:user2@domain.com",
    timeout: 30,
    codecs: ["PCMU", "PCMA", "OPUS"],
    headers: [
      { name: "X-Custom-Header", value: "custom-value" }
    ],
    callStateUrl: "https://example.com/call-state-webhook",
    callStateEvents: ["created", "ringing", "answered", "ended"],
    maxPricePerMinute: 0.50
  }));

const call = await client.voice.dial(devices);

Example​

Constructors​

constructor​

Example​

Properties​

Methods​

add​

Parameters​

Returns​

Example​

Phone​

Parameters​

Returns​

Example​

Sip​

Parameters​

Returns​

Example​

Example

Constructors

constructor

Example

Properties

Methods

add

Parameters

Returns

Example

Phone

Parameters

Returns

Example

Sip

Parameters

Returns

Example