Copy page

Deep Linking

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. These parameters can also be retrieved when getting the call resource through the Spoke API.

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 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:

Code
{
  ...,
  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