# Dial

## Dial a number

`spoke://dial?contactNumber={contactNumber}&callerId={callerId}`

Dials a contact number using a specified caller ID.

#### Parameters

- **contactNumber** - The phone number to dial in +E164 format.
  - If `contactNumber` is not provided, the app will open the Dial Pad.
  - If `contactNumber` is invalid, it will be prefilled in the Dial Pad, allowing the user to edit it.
- **callerId** (optional) - The caller ID to use for the call.
  - If `callerId` is not provided, the call will be made using the user's default caller ID.
  - `callerId` must be from the list of available caller IDs assigned to the user. If the `callerId` is invalid, the app will prompt the user to select a valid one.
  - If `callerId` is valid but `contactNumber` is invalid, the valid `callerId` will be preselected in the Dial Pad.

#### Example

`spoke://dial?contactNumber=%2B64221112222&callerId=%2B14341112222`

**Note**: Both `%2B64221112222` and `%2B14341112222` are URI-encoded +E164 phone numbers, but the Spoke Phone app is able to handle `+64221112222` as well.

#### Passthrough parameters

The Spoke Phone app supports passthrough parameters when dialling a contact via a deep link. Passthrough parameters are stored against the call record and are then included in the call's [webhook events](/webhook-events). These parameters can also be retrieved when [getting the call resource through the Spoke API](/api/calls#get-a-call).

Use passthrough parameters to track a call made by a user from a link in an external application (such as a CRM or in-house system) and associate the outcome of the call (including call recordings and any other records created by the Spoke platform) with the external platform. See [Passthrough Parameters](/passthrough-parameters) for every mechanism that can set them and everywhere they are returned.

To attach passthrough parameters to a call, add them to the deep link URL as a query string parameter with the parameter name prefixed with `x-`, e.g.:

`spoke://dial?contactNumber=%2B64221112222&callerId=%2B14341112222&x-contactId=HS12345&x-orderId=OR12345`

Opening the above deep link URL will result in the `call` object in the webhook event payload and the call resource in the API to contain a `passthroughParameters` object containing the exact parameters provided in the deep link URL:

```json
{
  ...,
  passthroughParameters: {
    "x-contactId": "HS12345",
    "x-orderId": "OR12345"
  }
}
```

The passthrough parameters in the deep link URL are limited to a total of 1000 bytes.

If the total size of the passthrough parameters exceeds 1000 bytes, the call will not be made and the Spoke app will navigate to the dial pad, prefilled with provided the contactNumber and callerId.

Passthrough parameters will not be stored against the call if opening the deep link results in the call not being made. This includes the following scenarios:

- The passthrough parameters exceeds the limit of 1000 bytes and the user subsequently presses the dial button on the dial pad.
- The contactNumber is invalid and the user subsequently edits the number on the dial pad and presses the dial button.
- The callerId is invalid and the user subsequently selects a valid callerId on the dial pad and presses the dial button.
- No contactNumber is provided and the user subsequently enters a number on the dial pad and presses the dial button.

**It is important to ensure that the source system implements appropriate validation of all required parameters. This includes ensuring that:**

- `callerId` MUST be a valid +E164 number
- `contactNumber` MUST be a valid +E164 number
- Passthrough parameter length does not exceed the documented limit