> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# dial

> Initiate an outbound call.

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

## **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`** `string` — required

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 | undefined` — default: 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`][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_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)

```typescript {12}
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)

```typescript {12}
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();
```

> Initiate an outbound call.