Skip to main content

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.

const plan = new Voice.DeviceBuilder()
  .add(
    Voice.DeviceBuilder.Sip({
      from: "sip:user1@domain.com",
      to: "sip:user2@domain.com",
      timeout: 30,
    })
  )
  .add([
    Voice.DeviceBuilder.Phone({ to: "+yyyyyy", timeout: 30 }),
    Voice.DeviceBuilder.Phone({ to: "+zzzzzz", timeout: 30 }),
  ]);

Constructors​

constructor​

• new DeviceBuilder()

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

Example​

const plan = new Voice.DeviceBuilder();

Properties​

devices​

Get the list of devices that have been added to this DeviceBuilder.

Syntax: DeviceBuilder.devices

Returns: NestedArray<Object>

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​

NameTypeDescription
deviceObject | object[]A single device or an array of devices. See Phone and Sip.

Returns​

DeviceBuilder

Example​

Adding two devices in series. If "+xxxxxx" doesn't answer within 30 seconds, "+yyyyyy" will be called.

const plan = new Voice.DeviceBuilder()
  .add(Voice.DeviceBuilder.Phone({ to: "+xxxxxx", timeout: 30 }))
  .add(Voice.DeviceBuilder.Phone({ to: "+yyyyyy", timeout: 30 }));

client.dial(plan);

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

const plan = new Voice.DeviceBuilder().add([
  Voice.DeviceBuilder.Phone({ to: "+xxxxxx", from: "+aaaaa", timeout: 30 }),
  Voice.DeviceBuilder.Phone({ to: "+yyyyyy", from: "+bbbbb", timeout: 30 }),
]);

client.dial(plan);

Mixing series and parallel. First calls the SIP device. If it doesn't answer, calls "+yyyyyy" and "+zzzzzz" simultaneously.

const plan = new Voice.DeviceBuilder()
  .add(
    Voice.DeviceBuilder.Sip({
      from: "sip:user1@domain.com",
      to: "sip:user2@domain.com",
      timeout: 30,
    })
  )
  .add([
    Voice.DeviceBuilder.Phone({ to: "+yyyyyy", from: "+aaaaa", timeout: 30 }),
    Voice.DeviceBuilder.Phone({ to: "+zzzzzz", from: "+bbbbb", timeout: 30 }),
  ]);

client.dial(plan);

Phone​

▸ Static Phone(params): Object

Represents the configuration to call a phone device.

Parameters​

NameTypeDescription
paramsObject-
params.callStateEventsstring[]An optional array of event names to be notified about. Allowed values are created, ringing, answered, and ended. Default is ended.
params.callStateUrlstringOptional webhook URL to which SignalWire will send call status change notifications. See the payload specifications under CallState.
params.tostringNumber to call, in E.164 format.
params.fromstringSignalWire number to use to initiate the call, in E.164 format.
params.maxPricePerMinute?numberThe 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.
params.timeout?numberTime to wait for the call to be answered, in seconds. Optional. Default is 30 seconds.

Returns​

Object

Example​

Voice.DeviceBuilder.Phone({
  to: "+xxxxxx",
  from: "+aaaaa",
  timeout: 30,
  callStateUrl: "http://mydomain.com/hook",
  callStateEvents: ["ended", "answered"],
});

Sip​

▸ Static Sip(params): Object

Represents the configuration to call a SIP device.

Parameters​

NameTypeDescription
paramsObject-
params.fromstringSIP endpoint URI to use to initiate the call.
params.callStateEventsstring[]An optional array of event names to be notified about. Allowed values are created, ringing, answered, and ended. Default is ended.
params.callStateUrlstringOptional webhook URL to which SignalWire will send call status change notifications. See the payload specifications under CallState.
params.tostringSIP endpoint URI to call.
params.codecs?SipCodec[]Optional array of desired codecs in order of preference.
params.headers?SipHeader[]Optional array of headers. Must be X- headers only.
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?numberTime to wait for the call to be answered, in seconds. Default is 30 seconds.

Returns​

Object

Example​

Voice.DeviceBuilder.Sip({
  from: "sip:user1@domain.com",
  to: "sip:user2@domain.com",
  timeout: 30,
  callStateUrl: "http://mydomain.com/hook",
  callStateEvents: ["ended", "answered"],
});