Outbound Call

The Outbound Call Data Action allows you to programmatically change the default state/configuration of an outbound Spoke call, right as the call is about to be placed.

When you set up Spoke, you set up company defaults for items such as call recording, the CallerIDs external contacts see when your team make calls, etc. Outbound Data Actions allow you to change this default behavior on a call-by-call basis.

These are the actions that are supported by Outbound Call Data Action:

Override Dial Permission

Allow or block any outbound call made to the specified phone number. Applies to all calls, whether made from the Spoke Phone application or a SIP device. For SIP device calls, this overrides the flag set against "Outbound calls allowed".

Override Outbound Caller ID

Overrides the caller ID for any outbound call made.

Passthrough Parameters

Overrides the passthrough parameters associated with the outbound call. Passthrough parameters can be attached to an outbound call using Spoke's Deep Linking dial verb. See Passthrough Parameters for the full picture of how they are set and returned.

Existing passthrough parameters are included in the GET request and are flattened and appended to the query string as key-value pairs.

Passthrough parameters from the data action response will be merged with the existing passthrough parameters associated with the call. If a key exists in both the response and the current passthrough parameters, the value from the response will override the existing value.

The maximum size of passthrough parameters is 1000 bytes. If the merged passthrough parameters exceed 1000 bytes, then the passthrough parameters from the response will be discarded, and the stored passthrough parameters will not be updated.

Request and Response

Spoke sends an HTTP GET request with the parameters defined in the Outbound Call Request Payload, and expects an Outbound Call Response within 2 seconds. If no response payload is returned, the call will proceed as planned, using the original configuration for the call.

The request parameters for this Data Action will vary based on how the call is initiated:

If the call is initiated by a user or a SIP device attached to the user, the request will include the userId, userExtension, and userEmail parameters. No device-related parameters will be included.
If the call is initiated by a standalone SIP device, the request will not include any user-related parameters and will include the deviceId, deviceExtension, and deviceAddress parameters instead.

Passthrough Parameters

The existing passthrough parameters are flattened into key-value pairs, URL-encoded, and then appended to the query string.

Example:

Given a call with the following passthrough parameters:


Code
{
  "x-customerName": "John Doe",
  "x-item": "Smartphone & Accessories"
}

The constructed data action request will be:

Code
https://api.example.com/outboundCall?callerId=1234&contactNumber=%2B12178888888&vendorCallId=4321&x-customerName=John%20Doe&x-item=Smartphone%20%26%20Accessories

Outbound Call request

GET

https://your-data-action-endpoint.example.com

/outbound-call

Spoke sends this request to the Data Action URL you configure, with the fields below as query parameters.

Outbound Call request › query Parameters

callerId

string · required

The Caller ID or ANI that Spoke is proposing to use for placing this call.

contactNumber

string · required

The phone number being called.

vendorCallId

string · required

The vendor's identifier for the call.

callId

string

The Spoke ID of the call.

contactEmail

string

The email address of the contact being called.

contactId

string

The ID of the contact being called.

deviceAddress

string

The SIP address of the standalone SIP device that is placing the call.

deviceExtension

string

The extension of the standalone SIP device that is placing the call.

deviceId

string

The id of the standalone SIP device that is placing the call.

userEmail

string

The email address of the Spoke Phone user who is placing the call.

userExtension

string

The extension of the Spoke Phone user who is placing the call.

userId

string

The id of the Spoke Phone user who is placing the call.

Outbound Call request › Responses

200

Return the payload below within 2 seconds.

OutboundCallResponsePayload

callerId

string

Returning this parameter will override the Caller ID that Spoke (or the user) has selected. The value must be in a valid E164 format and be a verified caller ID in the account.

dialPermission

string · enum

Outbound Dial permission. Return either of the following values:

blocked: Prevents the call from taking place. The call status will show as Blocked in call history.
allowed: Allow the call to be made. This is the default value for this parameter if it is not included in the response payload. For SIP devices, the value needs to be explicitly set to override the "Outbound calls allowed" flag set against the SIP device.

Enum values:

allowed

blocked

passthroughParameters

CallPassthroughParametersResponse

If specified, updates the passthrough parameters stored against the call by merging the existing passthrough parameters with the returned passthrough parameters. If a key exists in both the existing passthrough parameters and the returned passthrough parameters, the returned parameter value will overwrite the existing value.

Each passthrough parameter key must start with the prefix x- and the value must be a string. Otherwise, the parameter will be ignored.

The maximum size of passthrough parameters is 1000 bytes. If the merged passthrough parameters exceed 1000 bytes, then the stored passthrough parameters will not be updated.

Example:


Code
{
  "x-contactId": "HS12345",
  "x-orderId": "ORD12345"
}

Insights Team Call

Request and Response

The request parameters for this Data Action will vary based on how the call is initiated:

If the call is initiated by a user or a SIP device attached to the user, the request will include the userId, userExtension, and userEmail parameters. No device-related parameters will be included.

If the call is initiated by a standalone SIP device, the request will not include any user-related parameters and will include the deviceId, deviceExtension, and deviceAddress parameters instead.

Passthrough Parameters

The existing passthrough parameters are flattened into key-value pairs, URL-encoded, and then appended to the query string.

Example:

Given a call with the following passthrough parameters:

Code

{
  "x-customerName": "John Doe",
  "x-item": "Smartphone & Accessories"
}

The constructed data action request will be:

Code

https://api.example.com/outboundCall?callerId=1234&contactNumber=%2B12178888888&vendorCallId=4321&x-customerName=John%20Doe&x-item=Smartphone%20%26%20Accessories

Outbound Call request

GET

https://your-data-action-endpoint.example.com

/outbound-call

Spoke sends this request to the Data Action URL you configure, with the fields below as query parameters.

Outbound Call request › query Parameters

callerId

string · required

The Caller ID or ANI that Spoke is proposing to use for placing this call.

contactNumber

string · required

The phone number being called.

vendorCallId

string · required

The vendor's identifier for the call.

callId

string

The Spoke ID of the call.

contactEmail

string

The email address of the contact being called.

contactId

string

The ID of the contact being called.

deviceAddress

string

The SIP address of the standalone SIP device that is placing the call.

deviceExtension

string

The extension of the standalone SIP device that is placing the call.

deviceId

string

The id of the standalone SIP device that is placing the call.

userEmail

string

The email address of the Spoke Phone user who is placing the call.

userExtension

string

The extension of the Spoke Phone user who is placing the call.

userId

string

The id of the Spoke Phone user who is placing the call.

Outbound Call request › Responses

200

Return the payload below within 2 seconds.

OutboundCallResponsePayload

callerId

string

Returning this parameter will override the Caller ID that Spoke (or the user) has selected. The value must be in a valid E164 format and be a verified caller ID in the account.

dialPermission

string · enum

Outbound Dial permission. Return either of the following values:

blocked: Prevents the call from taking place. The call status will show as Blocked in call history.
allowed: Allow the call to be made. This is the default value for this parameter if it is not included in the response payload. For SIP devices, the value needs to be explicitly set to override the "Outbound calls allowed" flag set against the SIP device.

Enum values:

allowed

blocked

passthroughParameters

CallPassthroughParametersResponse

Each passthrough parameter key must start with the prefix x- and the value must be a string. Otherwise, the parameter will be ignored.

The maximum size of passthrough parameters is 1000 bytes. If the merged passthrough parameters exceed 1000 bytes, then the stored passthrough parameters will not be updated.

Example:


Code
{
  "x-contactId": "HS12345",
  "x-orderId": "ORD12345"
}