dial | SignalWire

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.

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

devices[][].params

Record<string, unknown>Required

Device-specific parameters.

devices[][].params.to_number

stringRequired

Destination phone number in E.164 format (for "phone" type).

devices[][].params.from_number

stringRequired

Caller ID phone number in E.164 format (for "phone" type).

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 120000

How long in milliseconds to wait for the dial to complete (answer or failure) before throwing a timeout error.

Returns

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

Examples

Simple outbound call

1 import { RelayClient } from '@signalwire/sdk';
2 
3 const client = new RelayClient({
4   project: process.env.SIGNALWIRE_PROJECT_ID!,
5   token: process.env.SIGNALWIRE_TOKEN!,
6   contexts: ['default']
7 });
8 
9 await client.connect();
10 
11 const call = await client.dial(
12   [[{
13     type: 'phone',
14     params: {
15       from_number: '+15551234567',
16       to_number: '+15559876543',
17       timeout: 30,
18     },
19   }]]
20 );
21 const action = await call.play([{ type: 'tts', text: 'Hello!' }]);
22 await action.wait();
23 await call.hangup();
24 
25 await client.disconnect();

Serial dial (failover)

1 import { RelayClient } from '@signalwire/sdk';
2 
3 const client = new RelayClient({
4   project: process.env.SIGNALWIRE_PROJECT_ID!,
5   token: process.env.SIGNALWIRE_TOKEN!,
6   contexts: ['default']
7 });
8 
9 await client.connect();
10 
11 // Try the first number, then fall back to the second
12 const call = await client.dial([
13   [{ type: 'phone', params: { to_number: '+15551111111', from_number: '+15550000000' } }],
14   [{ type: 'phone', params: { to_number: '+15552222222', from_number: '+15550000000' } }],
15 ]);
16 
17 await client.disconnect();

Parallel dial (ring all)

1 import { RelayClient } from '@signalwire/sdk';
2 
3 const client = new RelayClient({
4   project: process.env.SIGNALWIRE_PROJECT_ID!,
5   token: process.env.SIGNALWIRE_TOKEN!,
6   contexts: ['default']
7 });
8 
9 await client.connect();
10 
11 // Ring both numbers simultaneously, first to answer wins
12 const call = await client.dial([[
13   { type: 'phone', params: { to_number: '+15551111111', from_number: '+15550000000' } },
14   { type: 'phone', params: { to_number: '+15552222222', from_number: '+15550000000' } },
15 ]]);
16 
17 await client.disconnect();