dial

Initiate an outbound call. Sends a calling.dial JSON-RPC request and waits for the server to return a calling.call.dial event confirming the call was answered or failed. Returns a fully-initialized Call object with valid callId and nodeId.

The devices parameter supports both serial and parallel dialing strategies. Each inner array represents a set of devices to ring simultaneously (parallel). The outer array represents sequential attempts — if the first group fails, the next group is tried.

Throws RelayError if the dial fails or if no answer is received within the dialTimeout period. The default timeout is 120 seconds.

Parameters

devices

Record<string, unknown>[][]Required

Nested array of device definitions for serial and parallel dialing. Each device is an object with type and params keys. You can also put the fields flat next to type; the SDK wraps them in params and, for "phone", maps to and from to to_number and from_number.

Serial dial (try one after another): each inner array has one device
Parallel dial (ring simultaneously): one inner array with multiple devices

devices[][].type

stringRequired

Device type. Valid values:

"phone" — PSTN phone number
"sip" — SIP endpoint
"fabric" — a resource address. The platform resolves the address to whatever it points to, such as a subscriber or a Relay application, and rings every live registration of a subscriber at once.

devices[][].params

Record<string, unknown>Required

Device-specific parameters. Which fields are required depends on the device type.

devices[][].params.to_number

string

Destination phone number in E.164 format. Required for "phone".

devices[][].params.from_number

string

Caller ID phone number in E.164 format. Required for "phone".

devices[][].params.to

string

Destination resource address. Required for "fabric".

devices[][].params.from

string

Caller ID shown to the destination (for "fabric").

devices[][].params.timeout

number

Per-device ring timeout in seconds.

options

object

Optional second argument with dial configuration.

options.tag

string | undefined

Client-provided correlation tag for event matching. Auto-generated as a UUID if not supplied.

options.maxDuration

number | undefined

Maximum call duration in seconds. The call is automatically ended when this limit is reached.

options.dialTimeout

number | undefinedDefaults to 120

How long in seconds to wait for the dial to complete (answer or failure) before throwing a timeout error. Matches the Python SDK convention.

Returns

Promise<Call> — A call object with all properties populated and ready for call control operations.

Examples

Simple outbound call

import { RelayClient } from '@signalwire/sdk';
const client = new RelayClient({
  project: process.env.SIGNALWIRE_PROJECT_ID!,
  token: process.env.SIGNALWIRE_API_TOKEN!,
  contexts: ['default']
});
await client.connect();
const call = await client.dial(
  [[{
    type: 'phone',
    params: {
      from_number: '+15551234567',
      to_number: '+15559876543',
      timeout: 30,
    },
  }]]
);
const action = await call.play([{ type: 'tts', text: 'Hello!' }]);
await action.wait();
await call.hangup();
await client.disconnect();

Serial dial (failover)

import { RelayClient } from '@signalwire/sdk';
const client = new RelayClient({
  project: process.env.SIGNALWIRE_PROJECT_ID!,
  token: process.env.SIGNALWIRE_API_TOKEN!,
  contexts: ['default']
});
await client.connect();
// Try the first number, then fall back to the second
const call = await client.dial([
  [{ type: 'phone', params: { to_number: '+15551111111', from_number: '+15550000000' } }],
  [{ type: 'phone', params: { to_number: '+15552222222', from_number: '+15550000000' } }],
]);
await client.disconnect();

Parallel dial (ring all)

import { RelayClient } from '@signalwire/sdk';
const client = new RelayClient({
  project: process.env.SIGNALWIRE_PROJECT_ID!,
  token: process.env.SIGNALWIRE_API_TOKEN!,
  contexts: ['default']
});
await client.connect();
// Ring both numbers simultaneously, first to answer wins
const call = await client.dial([[
  { type: 'phone', params: { to_number: '+15551111111', from_number: '+15550000000' } },
  { type: 'phone', params: { to_number: '+15552222222', from_number: '+15550000000' } },
]]);
await client.disconnect();