***

title: dial
slug: /reference/typescript/relay/client/dial
description: Initiate an outbound call.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[call]: /docs/server-sdks/reference/typescript/relay/call

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`][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.

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

## **Parameters**

<ParamField path="devices" type={"Record<string, unknown>[][]"} required={true} toc={true}>
  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
</ParamField>

<Indent>
  <ParamField path="devices[][].type" type="string" required={true} toc={true}>
    Device type. Valid values:

    * `"phone"` -- PSTN phone number
    * `"sip"` -- SIP endpoint
  </ParamField>

  <ParamField path="devices[][].params" type="Record<string, unknown>" required={true} toc={true}>
    Device-specific parameters.
  </ParamField>

  <Indent>
    <ParamField path="devices[][].params.to_number" type="string" required={true} toc={true}>
      Destination phone number in E.164 format (for `"phone"` type).
    </ParamField>

    <ParamField path="devices[][].params.from_number" type="string" required={true} toc={true}>
      Caller ID phone number in E.164 format (for `"phone"` type).
    </ParamField>

    <ParamField path="devices[][].params.timeout" type="number" toc={true}>
      Per-device ring timeout in seconds.
    </ParamField>
  </Indent>
</Indent>

<ParamField path="options" type="object" toc={true}>
  Optional second argument with dial configuration.
</ParamField>

<Indent>
  <ParamField path="options.tag" type="string | undefined" toc={true}>
    Client-provided correlation tag for event matching. Auto-generated as a UUID if
    not supplied.
  </ParamField>

  <ParamField path="options.maxDuration" type="number | undefined" toc={true}>
    Maximum call duration in seconds. The call is automatically ended when this
    limit is reached.
  </ParamField>

  <ParamField path="options.dialTimeout" type="number | undefined" default="120000" toc={true}>
    How long in milliseconds to wait for the dial to complete (answer or failure) before
    throwing a timeout error.
  </ParamField>
</Indent>

## **Returns**

`Promise<`[`Call`][call]`>` -- A call object with all properties populated and ready for call control operations.

## **Examples**

### Simple outbound call

```typescript {11}
import { RelayClient } from '@signalwire/sdk';

const client = new RelayClient({
  project: process.env.SIGNALWIRE_PROJECT_ID!,
  token: process.env.SIGNALWIRE_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)

```typescript {12}
import { RelayClient } from '@signalwire/sdk';

const client = new RelayClient({
  project: process.env.SIGNALWIRE_PROJECT_ID!,
  token: process.env.SIGNALWIRE_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)

```typescript {12}
import { RelayClient } from '@signalwire/sdk';

const client = new RelayClient({
  project: process.env.SIGNALWIRE_PROJECT_ID!,
  token: process.env.SIGNALWIRE_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();
```