Spoke API Reference (2026-06-05)

Welcome to the Spoke Developer API. This API allows you to connect Spoke Phone and Spoke Enlighten to your existing business systems in a variety of ways:

• Access the Spoke Unified Directory via the Directory endpoint. This endpoint provides comprehensive details about each Directory entry, including Availability. You can read more about the Spoke Directory and its core concepts here
• Upload customer, supplier and other CRM contacts into Spoke Phone via the Phonebooks and Contacts endpoint. Once integrated, these contacts become searchable in the Spoke mobile application external phonebook. Any new incoming calls from phone numbers that have matching details in the phonebook will automatically show enhanced caller ID details.
• Access detailed call logs via the Calls endpoint. You can extract this data for reporting, real-time analytics or even integrate them back into customer records in your CRM system.
• View Spoke User status via the Users endpoint, and build a custom dashboard to see who is available in real-time.
• Add SIP trunk extensions to the Spoke Unified Directory by managing your Spoke SIP Trunk integration via the Trunks endpoint. Integrating with this endpoint and its associated Trunk Devices, Trunk Users and Trunk Queues endpoints allows you to synchronise your legacy internal phone directory with Spoke, giving your Spoke users a unified view across your entire organisation.
• Subscribe to webhook events so that your systems can be notified when call and conversation related events occur on the Spoke platform.
• Send system generated SMS messages via the Conversations /conversationMessages endpoint. The messages will be automatically added to the user's conversations in the Spoke application.
• Create Data Actions to customise your call workflows
• Automatically analyse calls and conversations using the Spoke Enlighten AI Content Analysis /contentAnalysis endpoint.

If you have a Spoke account, you can access the Spoke Developer API via https://integration.spokephone.com. This production endpoint provides access to your live user data.

If you do not have a Spoke account, you have two options:

• If you have your own Twilio account and want to deploy Spoke into that account, enabling you to integrate Spoke with other Twilio applications, go to https://account.spokephone.com/twilio to create a free developer account.
• If you want use Spoke's services without needing your own Twilio account, go to https://account.spokephone.com/signup to sign up for trial account.

Either account will allow you to get started and provides access to full production functionality.

If you have requests, feedback or questions, please request to join the Spoke Phone Tech Community on Slack at https://spoke-phone-tech.slack.com

The Spoke API uses OAuth v2.0 client credentials flow to authenticate requests. You can manage your API access in the Spoke Account Portal at https://account.spokephone.com/login

To authenticate with the Spoke API you need to follow these steps:

1. Create an API key
2. Generate an Access Token
3. Make Authenticated Requests

For more details on the OAuth 2.0 client credentials flow, see the overview at https://auth0.com/docs/flows/concepts/client-credentials

You must first login as an Administrator to your account in the Spoke Phone Account Portal at https://account.spokephone.com/login. Open the settings page, click Other, Developers, and add a new API key. This is a one time operation.

Once the "API key" is created, you will be provided with the necessary details (OAuth 2.0 Client ID, OAuth 2.0 client secret, Authentication service URL) needed to create an access token.

Once you have created an "API key", the next step is to obtain a bearer token from the Spoke Phone Auth Service at https://auth.spokephone.com/oauth/token. This step requires making an HTTP POST to the Authorization Service URL provided in the step above, with the request body containing an application/x-www-form-urlencoded string with the following fields:

A javascript example of this is below:

const response = await fetch("https://auth.spokephone.com/oauth/token", {
  method: 'post',
  body: querystring.stringify({
    client_id: "{CLIENT_ID_FROM_DEVELOPER_API}",
    client_secret: "{CLIENT_SECRET_FROM_DEVELOPER_API}",
    grant_type: "client_credentials"
  }),
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
});

const { access_token } = response.json();

Note: The auth token endpoint still supports sending an application/json body, however this content type is deprecated in favour of application/x-www-form-urlencoded.

To make authenticated API requests, you must provide a valid bearer token in an HTTP Header:

Authorization: Bearer {access_token}

Once you have obtained an access token, you must provide this as a Bearer token for all subsequent API requests.

const response = await fetch("https://integration.spokephone.com/phonebooks", {
  method: "get",
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${access_token}` },
});

Access tokens expire after 3600 seconds (1 hour). It is up to the developer to implement appropriate refresh logic, by following the same token generation process above. Note that as flow is a client credentials flow, intended for machine to machine operations, we do not provide a token refresh endpoint. Instead, requesting a new access token using the same client_id/client_secret is sufficient.

The API is RESTful. All requests should be made over HTTPS, and accessed from https://integration.spokephone.com.

Requests

Most of the parameters and request data will be contained in the body of the HTTP request. The Spoke Phone API accepts JSON in the HTTP request body. No other data format (e.g. XML) is supported.

Responses

The success or failure of an HTTP request is returned as a standard HTTP status code:

• a 2xx code for success
• a 4xx or 5xx code for failure

The response body will always be encoded in JSON format. No other data format (e.g. XML) is supported.

The Spoke Phone API uses a cursor based model for paging of large result sets. Paging support is available for the following endpoints:

• GET /phonebooks
• GET /phonebooks/{id}/contacts
• GET /calls
• GET /trunks
• GET /trunks/{trunkId}/trunkDevices
• GET /trunks/{trunkId}/trunkQueues
• GET /trunks/{trunkId}/trunkUsers

All of these endpoints support an optional limit parameter. If this parameter is omitted, the default limit is 100. The maximum limit is 1000 for any single request. You can retrieve a list of phonebooks without retrieving associated contacts with GET /phonebooks?limit=0

Example

GET https://integration.spokephone.com/calls?limit=2 HTTP/1.1
Host: integration.spokephone.com

200 Response

{
    "meta": {
        "next": "eyJsYXN0TW9kaWZpZWRUaW1lc3RhbXAiOjE1Njg2NzUzOTE3NTIsImNhbGxJZCI6ImE2YzVkMDgwLWQ0MWUtMTFlOS1hYzZiLWE5MTliMjAwYWFlNCIsIm9yZ2FuaXNhdGlvbklkIjoiOTQ4NzhhYzEtMDI3OS0xMWU5LWI0ZmEtNmJiYzgxMGEzZjJkIn0="
    },
    "calls": [ { ... }, { ... } ]
}

Endpoints that support paging return a meta field in the response object, which includes a next token to be used in subsequent requests.

Simply pass the next token in the query string of the next GET to retrieve the next page of results.

If there are no additional pages the next field will be empty.

Batch operations such as uploading a list of contacts requires replacing the entire contents of a given Phonebook. Additional batch upload support may be introduced in the future.

Individual PUTS and POSTS are limited to 6MB total (JSON encoded) data size. If a given Phonebook contains more than 6MB of data then it should be split into separate phonebooks, until such time that we introduce batch upload paging.

The GET /calls endpoint supports paging by last modified timestamp. This is because a call can have additional notes stored against it well after the call ends, and there is a small amount of latency between the call end and any recordings becoming available. The last modified timestamp will be updated whenever any additional data is stored against the call.

Calling a GET /calls?modified={timestamp} will retrieve all calls created or modified since the provided timestamp. This means that the API may return a Call that was returned in response to a previous request. It is the responsibility of the client application to reconcile the response content and upsert the retrieved calls as appropriate.

The timestamp value is a a numeric timestamp in milliseconds since the Unix epoch.

In general for any date/time or timestamp types, this API will provide two fields:

1. {fieldName}At: This is an ISO8601 formatted date/time. All date/times are UTC.
2. {fieldName}Timestamp: This is a numeric timestamp in milliseconds since the Unix epoch.

Download Postman Collection: Download

To use the postman collection you will need to have authentication credentials, which can be obtained in the Developer section of the Spoke Phone Account Portal (see Create an API key for more details on how to create API authentication credentials).

We recommend setting up the following variables in a postman environment clientId, clientSecret, tokenUrl, and baseUrl. To authenticate every request for the postman collection for an hour (the lifetime of an authentication token), you will need to edit the collection Authorization to use OAuth 2.0 with client credentials. Once you have completed this setup you will be able to make any request in the collection, and be authenticated to do so.

Each item in the Spoke directory is called a directory entry. Spoke's core directory entry types are userWithAvailability, teamWithAvailability and device. If you have enabled our PBX augmentation feature, then a Directory can also contain trunkUser, trunkDevice and trunkGroup types - these are equivalent to the device type with some additional attributes for display and search purposes.

Devices

In Spoke, you can add a SIP Device as a standalone Device, and it will appear as an entry in a Spoke directory. In Spoke, a SIP Device only provides basic dialtone and call audio functionality. Rich functionality is available through Spoke's desktop and mobile softphone applications, and we recommend SIP devices are only used for common area or conference room phones.

Note: Spoke does not currently support adding a Twilio client as a standalone entry in the Spoke directory. Instead, Twilio clients are automatically created when you add a Spoke user and they sign in using the Spoke mobile or desktop applications.

Users

In Spoke, a User can have multiple callable endpoints, for example:

• a Mobile phone running the Spoke mobile application for iOS or Android
• a Desktop PC running the Spoke desktop application for MacOS or Android
• a SIP Device registered to the Twilio SIP Registrar or to a third party PBX interconnected via a SIP Trunk

When a call arrives on Spoke for a given User, Spoke will dial all endpoints associated with that User. The endpoint that is answered wins and Spoke automatically stops ringing the user's other endpoints. Additionally, the user can transparently move the call from one endpoint to another, enabling them to answer a call at their desk and continue it on their mobile phone when leaving the office.

Call Groups/Teams

A Team (or Call Group) in Spoke is analogous to a hunt group in traditional PBX systems. A Team consists of one or more User or Device members, and has business rules that define how a call is routed to those members, as well as what happens when the call goes unanswered. When a call arrives on Spoke for a Team, Spoke will automatically create a call offer flow that dials the members of the team based on those pre-defined rules. For User team members, the same dial rules apply, which means that when the call is offered to the User, all of the user's endpoints are dialled at once.

Company Contacts are external contacts that are managed via the Phonebooks and Contacts endpoints.

Spoke supports two types of phonebooks:

• Company Contacts (Shared): Contacts in shared phonebooks are searchable and visible to all users of the Spoke application.
• Company Contacts (Assigned): Contacts in assigned phonebooks are searchable and visible only to the user who is assigned that phonebook.

All Company Contacts are searchable and visible in the Spoke application under the 'External' tab. They are not editable by end-users and must be managed through the Spoke API.

Company Contacts (Shared)

Shared company contacts are used where you do not need to restrict which users can access a contact.

You can create and manage multiple Shared phonebooks, these are searchable and visible to all users.

Company Contacts (Assigned)

Each Spoke User also has a phonebook that contains company contacts that only they can see or search. This is useful for use cases where you need to restrict which contacts a user has access to.

You manage a user's phonebook via the creating or updating a personal phonebook endpoint, using the user's email address as follows:

PUT https://integration.spokephone.com/phonebooks/email@example.com

Every entry in the Spoke directory is assigned an extension number.

Extensions are the primary mechanism for connecting calls that have already been answered by another Twilio application (such as Studio) to entries in the Spoke Directory. We do not, however, use extensions for internal call routing.

Extensions are created and managed through the Spoke account portal, and can be assigned to any Device, Team or User in your account. Extensions are unique, and there is a one to one mapping between extension and directory entry.

All Spoke calls involve a conference bridge; this allows us to support warm transfer, multi-party calls, recording and other functionality.

This means that when a call arrives on the Spoke platform, the incoming call is placed into a conference via <Dial><Conference>... TwiML. We then use Twilio's Create Call REST API to dial all endpoints based on the target of the incoming call (a Device, Team or User as described above). When the call is answered by one of the endpoints, all other calls are cancelled, and the "winning" call is placed into the same conference.

When you activate a phone number from your Twilio account on Spoke, the Spoke platform automatically attaches Spoke's standard inbound TwiML application to the phone number. From that point forward, all routing and call handling is taken care of by Spoke.

If you want greater control over a call, including the ability to send a call to Spoke and have Spoke send the call back to your application if the call goes unanswered, then we recommend using Spoke's redirect handler.

The Spoke redirect handler enables you to programmatically connect incoming calls that have been processed with other Twilio applications (such as Studio, Flex or your own application) to Spoke.

The redirect handler url has the following form:

https://api.spokephone.com/telephony/redirect?extension={EXTENSION}&organisationId={YOUR_ORGANISATION_ID}

The handler accepts the following parameters:

Note: The parameter order listed below is important as all requests to the handler are signature validated.

Note: The Spoke Directory API provides a pre-formed twimlRedirectUrl for each directory entry that includes the correct extension and organisationId parameters.

To connect an incoming Twilio call with a Spoke directory entry, simply update the call using Twilio's REST API as follows:

const client = require('twilio')();

client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
  .update({
    method: 'POST',
    url: 'https://api.spokephone.com/telephony/redirect?extension={EXTENSION}&organisationId={SPOKE_ORG_ID}'
  });

This will connect the incoming call to Spoke and follow the dial rules outlined in the Spoke Directory section above.

If sendToVoicemail is true, then Spoke will send the call to the target extension's voicemail, if that extension is a type that supports voicemail. Once the customer leaves a voicemail, the call ends. User and Team extensions will always have a voicemail, however other directory entry types do not currently support voicemail. In the case of extensions that do not support voicemail, there are two possible scenarios:

• If returnTo/returnToId are provided, then the call will be returned to the target defined by returnToId as described in the section Returning unanswered calls below
• If returnTo/returnToId are not provided, the call will silently end. Due to this behaviour, we recommend that returnTo and returnToId are always provided

It is important to note that if sendToVoicemail is true then Spoke will never ring the target extension, instead the call goes straight to the target extension's voicemail flow.

If you update the call with the redirect URL documented above, and only provide the extension and organisationId parameters, then Spoke's standard business rules kick in. This means that if the target extension is unavailable or does not answer, then Spoke's standard "unanswered call" rules apply:

• For calls to a User extension, the call will go the user's voicemail
• For calls to a Team extension, the call will follow the call group's "unanswered" call flow configuration - which could send the call to another call group, the group's voicemail or to an external PSTN number

To override this behaviour, and return control of the call back to your application, you have three options:

1. Return to a Studio Flow

Add &returnTo=flow&returnToId={FLOW_SID} to the url parameter in the update method above:

const client = require('twilio')();

client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
  .update({
    method: 'POST',
    url: 'https://api.spokephone.com/telephony/redirect?extension={EXTENSION}&organisationId={SPOKE_ORG_ID}&returnTo=flow&returnToId={STUDIO_FLOW_SID}'
  });

This will return the call to a Twilio Studio flow. If you have sent the call from the same flow by using the redirect widget, then you can control what happens next to the call by connecting a new widget to the return output of the redirect widget.

2. Send the call to a TaskRouter Workflow

Add &returnTo=taskQueue&returnToId={WORKFLOW_SID} to the url parameter in the update method above:

const client = require('twilio')();

client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
  .update({
    method: 'POST',
    url: 'https://api.spokephone.com/telephony/redirect?extension={EXTENSION}&organisationId={SPOKE_ORG_ID}&returnTo=taskQueue&returnToId={WORKFLOW_SID}'
  });

This will send the call to a Twilio Task Router Workflow, which could be attached to Flex, or a workflow/task queue that your own application listens to.

3. Send the call to an HTTPS endpoint

Add &returnTo=postEndpoint&returnToId={ENCODED_HTTPS_URL} to the url parameter in the update method above. This can be a Twilio Function or any HTTPS endpoint that accepts a POST request.

The following example will redirect the call to the provided URL.

const client = require('twilio')();

const returnToPostEndpoint = encodeURIComponent("https://example.com/return-post-endpoint");

client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
  .update({
    method: 'POST',
    url: `https://api.spokephone.com/telephony/redirect?extension={EXTENSION}&organisationId={SPOKE_ORG_ID}&returnTo=postEndpoint&returnToId=${returnToPostEndpoint}`
  });

Details about the request body sent by Twilio can be found here.

Note: The POST request will be sent by Twilio with an X-Twilio-Signature header. We recommend you secure the endpoint by validating that the request is coming from Twilio. For redirects to a Twilio Function, this can be done by setting the visibility of the Function to Protected.

Invalid URLs will be ignored and unanswered calls will not be returned.

Add &sendToVoicemail=true to the url parameter in the update method above:

const client = require('twilio')();

client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
  .update({
    method: 'POST',
    url: 'https://api.spokephone.com/telephony/redirect?extension={EXTENSION}&organisationId={SPOKE_ORG_ID}&sendToVoicemail=true'
  });

This will force Spoke's call flows to bypass availability checks and assume the target entry has no availability. In the case of a Team, it also bypasses unanswered call roll-over rules. The call will be sent directly to the target entry's voicemail. The target entry will:

• Receive a standard missed call/voicemail notification
• See a missed call in their call history
• Receive a voicemail email including transcript (if that option is enabled)

Note : As noted above, only User and Team extensions currently support voicemail.

If a valid number is provided as the timeout, then Spoke will use it as the number of seconds to wait for someone to answer the call before returning the call or sending it to voicemail.

• For calls to a User or a Device, this is the number of seconds Spoke will ring the user or the device.
  • The supported range of values for timeout when calling a user or a device is from 10 to 70 seconds. If the provided parameter falls outside the range, it will be rounded to the nearest supported value.
• For calls to a Team, this is the number of the seconds Spoke will wait for someone to answer the call before returning or forwarding the call.
  • The supported range of values for timeout when calling a team is from 10 to 300 seconds. If the provided parameter falls outside the range, it will be rounded to the nearest supported value.

If a valid number is provided as the nextOfferTimeout, then Spoke will use it as the number of seconds to wait for calls to a Team before offering the call to the next available user(s). The supported range of values for nextOfferTimeout is from 5 to 60 seconds. If the provided parameter falls outside the range, it will be rounded to the nearest supported value.

Note : The asynchronous nature of API calls between Spoke and Twilio coupled with the overhead of setting up and tearing down call legs means that timeout values are indicative only, and the follow on action may occur some number of seconds after the timeout expires.

If a valid value is provided as the priority, then Spoke will use it to:

• Determine which calls take priority when selecting the next call to queue for a user.
• Determine the order in which calls are offered to a user.

The supported range of values for priority is an integer value between 1 and 9, where 1 is the highest priority and 9 is the lowest. If the provided parameter falls outside the range, the call will be assigned a default value of 5.

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 with Redirect to track calls that have been initially handled by other Twilio applications (such as Studio, Flex or your own custom application), ensuring that the outcome of the call can be associated correctly with your external applications (such as CRM or in-house systems).

Examples of passthrough parameters include caller verification, IVR selections or other data collected from external systems during the initial phase of the call.

To attach passthrough parameters to a call, add them to the url parameter with the parameter name prefixed with x- when updating the call:

const client = require('twilio')();

client.calls
  .update({
      method: 'POST',
      url: 'https://api.spokephone.com/telephony/redirect?extension={EXTENSION}&organisationId={SPOKE_ORG_ID}&x-contactId=HS12345&x-orderId=OR12345'
  });

Important: All the query parameters of the url must be in alphabetical order. In the example above x-contactId must come before x-orderId.

• Size Limit: The total length of all passthrough parameters (including parameter names and values) must not exceed 1000 bytes. If this limit is exceeded, all passthrough parameters will be discarded.
• Processing: Parameter names and values are URL-decoded, validated for safety, and stored as-is upon input. No additional processing is performed.

Overview

You can get up and running quickly with Spoke and Twilio Studio by leveraging Spoke's Directory API and our open source Twilio Runtime Functions.

1. The Spoke Directory API provides you with programmable lookup into the Spoke Unified Directory. The response payload includes real time availability of Spoke Users and Teams, enabling you to make routing decisions based on real time presence and availability.
2. Get the Spoke Twilio Runtime functions here. These functions deploy into your Twilio account and give you quickstart access to the Spoke Directory API from Twilio Studio.

Before getting started, we recommend you read the Core Concepts section above to familiarise yourself with the Spoke Directory structure and how Twilio calls integrate with Spoke.

To follow along with this guide, you'll need a free Spoke developer account, deployed into your Twilio account, (get one at https://account.spokephone.com/twilio) and you should have set your Spoke account up with 1 or 2 users.

How To: Basic Studio Flow Using getExtension Function and twimlRedirectUrl

In this How To, we're going to show you how to quickly get a Twilio Studio flow connecting to Spoke using the Directory API and Twilio Runtime Functions.

The above Studio flow leverages the getExtension function to check availability of a Spoke directory entry, and if it is available send the call over to that extension.

1. Setup

To get started, you'll need to deploy the Spoke Twilio Runtime Functions into your account, then create a Studio Flow attached to a Twilio phone number, and add a Gather widget.

2. Add Run Function widget

To access one of the functions you just deployed from a Studio flow, drop a Run Function widget into your flow and connect it to the User Pressed Keys output out of your Gather widget. From here, select the SERVICE, ENVIRONMENT, and FUNCTION you want to run:

You will need to add one parameter to the function, called extension, and set the value to {{widgets.welcome_message.Digits}}.

The getExtension function returns the following fields by default.

1. displayName - The display label of the directory entry
2. type - The type (userWithAvailability, teamWithAvailability etc) of the directory entry
3. status - The current (real time) availability of the directory entry
4. availabilitySummary - Human readable availability summary
5. twimlRedirectUrl - Redirect the call to this url to connect the caller to the directory entry

You can change the function to return any directory entry fields - these are documented in the GET /directory section of the developer reference.

3. Add Split Widget

The split widget allows you to branch your flow based on a matching condition. Drop a Split widget into your flow and connect it to the Success output of the Run Function widget.

In this case we are branching based on the status field - and will only send the call to the directory entry associated with the extension if the entry is available. You can access the response body fields from the run function widget using the following path: {{widgets.[run_function_widget_name].parsed.[field_name]}}.

In this case, we want to check the availability status of the extension, so we check that the widgets.get_extension.parsed.status field is equal to available

4. Add Redirect Widget

The final step is to add the redirect widget which will send the incoming call across to the Spoke extension. Drop a TwiML Redirect widget into your flow and connect it to the If value equal to available output of the Split widget.

Configuring this widget is simple - you just need to set the URL field to {{widgets.get_extension.parsed.twimlRedirectUrl}}

5. Publish and test your flow

That's it! Now all you need to do is publish your flow, and test that it works.

To test, dial the incoming number attached to your Studio flow, and when you hear the gather prompt, enter the extension of one of your Spoke users. If you've configured everything correctly, the call should connect through to the user's softphone on Spoke.

Review

This How To has introduced you to creating a basic Studio flow connected to a Spoke softphone, using the Spoke Directory API and Runtime functions. This only scratches the surface of what you can build.

Here are some other ideas to explore:

• Return the caller back to the initial gather menu if the extension is not found
• Add a second gather widget to the No condition matches output of the Split widget and build a new flow around the extension being unavailable - maybe send the caller to a Flex queue.
• Use the optional returnTo and returnToId parameters to return the call to your flow if the call goes unanswered in Spoke.

Overview

The Power Automate package is provided as an example set of templates to get you started with the most common integration scenarios from Spoke to Dynamics 365. We expect anyone using the provided templates to accept and own the operation and management of these example Microsoft Power Automate flows and ensure it is fit for purpose in the environment it is installed.

Power Automate is a service that helps you create automated workflows between your favorite apps and services, to synchronize files, get notifications, collect and update data, and more.

Power Automate is an ideal solution for customers using Microsoft, to integrate new and existing workflows to Spoke Phone, and take advantage of owning the integration and business workflows end to end.

Spoke has created a set of example template flows to get a customer up and running with the most common scenarios using MS Power Automate to integrate Spoke to Dynamics 365.

Read the DISCLAIMER before downloading the samples

Download the User Guide

Download the Microsoft Power Automate to Dynamics 365 samples

Download the postman collection of sample Spoke webhook events

Spoke supports webhooks as a mechanism for notifying your systems when an event occurs. Webhooks are useful for listening to asynchronous events occurring on the Spoke platform, such as changes to a call's state over time; a change to the contact associated with a call; or a call recording becoming available.

To get started, you will need to configure a webhook in the Spoke account portal. Alternatively, you can use the Webhook API to configure a webhook. During configuration you will be given the option to specify event types you wish to receive notifications for. You will also be required to provide a valid, publicly routable HTTPS URL that accepts POST requests with the application/json content type.

Every Spoke event sent to your webhook is wrapped in the following standard wrapper that provides important information about the event, such as its type, a timestamp of when it was created, and the event data itself.

Once your application is configured to receive events, it will listen for any event sent to the endpoint. For security reasons, we strongly recommend that you ensure requests to your endpoint come from Spoke. The easiest method to validate that a request was sent via Spoke is to verify the signature, and timestamp sent in every request against the secret that was provided to you when you created your webhook.

Verifying the signature

A request is considered valid based on the following conditions:

• The x-spoke-timestamp header is a valid UNIX timestamp, and represents a time sent within the last 5 minutes (using millisecond precision). This header allows the consumer to validate when a request was sent, to avoid replay attacks.
• The x-spoke-signature header is formatted as sha256=<HMAC algorithm cipher text>, and it contains the correct hash based on the hexadecimal representation of the SHA256 HMAC algorithm with the signing secret applied to <x-spoke-timestamp header value>.<request body>. The calculated hash includes the timestamp to ensure that an attacker cannot modify the timestamp without also invalidating the message signature.

A request can be validated via the following:

const isValidSpokeRequest = (requestBody: string, signingSecret: string, spokeTimestamp: number, spokeSignature: string): boolean => {

  // Determine if timestamp is valid
  const isValidTimestamp = (Date.now() - spokeTimestamp) <= 300000; // 5 x 60 x 1000
  if (!isValidTimestamp) {
    return false;
  }

  // Determine if the signature is valid
  const [algorithm, cipher] = spokeSignature.split("=");
  const body = `${spokeTimestamp}.${requestBody}`

  const h = crypto.createHmac(algorithm, signingSecret);
  h.update(body);
  return h.digest("hex") === cipher;
}

Delivery Attempts

Spoke will attempt to deliver events to your webhooks 10 times, over the course of 24 hours with an exponential back off. For an event to be considered successfully delivered, your endpoint will need to respond with a valid 2XX HTTP status code within 5 seconds of the HTTP request being received. In the Developers section of the Account Portal, you can view all attempts to deliver an event to your endpoint.

Retries

Spoke will retry delivering a webhook event if the request fails and your endpoint responds with any of the following status codes:

• Server-side errors: 5xx
• Throttling errors: 429
• Request timeout errors: 408

Failed delivery attempts that respond with any other status codes will not be retried. For example, responses with a 400 status code (Bad Request) will not be retried, as it signals that repeating the same request will fail with the same error.

Automatic Disabling of Webhooks

In order to manage system capacity across the platform, Spoke will automatically disable a webhook once more than consecutive 1000 events have failed to deliver. The Spoke Administrator who created the webhook will be notified via email that the webhook has been disabled.

Order of Events

Spoke does not guarantee delivery of events in the order in which they are generated. Your endpoint should not expect delivery of events in order, and should handle these accordingly.

Below are some examples of when the above events might occur during the lifetime of some calls.

Note: These are example timelines. While most of the events will fire in a similar order to the ones given below, this is not guaranteed. See Order of Events for more details on how event ordering might affect your webhook.

Example Timelines of Call and Availability Events

Example 1 - Basic Call Timeline with User Answered Call

Example 2 - Unanswered Call to Team

Example 3 - Contact Assignment and Recording Transcript

Example Timelines of Conversation Events

Example 1

Example 2

• Added a new variant of POST /contentAnalysis request payload to support analyzing aggregated agent scorecards

• Added new licenses attribute to the UserWithAvailability type
  • Applies to GET /users, GET /users/{id}, GET /directory, GET /directory/{entryId}, the user.availability.updated webhook event, and the team.availability.updated webhook event

• Added new POST /conversationMessages endpoint
• Marked POST /messages and POST /teamMessages endpoints as deprecated
  • These endpoints have been replaced with POST /conversationMessages and will be removed in a future version of the API

• Added new optional query parameter email to GET /users endpoint

• Added optional notifyUsers attribute to:
  • POST /messages request payload
  • POST /teamMessages request payload
• Added webhook delivery retry documentation, including retryable status codes

• The Redirect API now accepts any valid HTTPS URL as the returnToId, when returnTo is set to postEndpoint

• Added optional preferences field to the Insights Data Action Response
  • Controls the preferred Insights context source and Enlighten cards display order
• Added support for group MMS
  • POST /teamMessages endpoint
  • Inbound Conversations Data Action Request Payload

• Added new participants and channel attributes to Conversation
  • These fields are surfaced in:
    • All conversation webhook events
    • The contact.shared event
• Added new author attribute to each message in messages attribute of Conversation
  • This is surfaced in all conversation webhook events

• Added a new GET /calls/{id}/contentAnalysis endpoint

• Added a new GET /contentAnalysis endpoint

• Added usage property to artifacts in:
  • The response payload of /contentAnalysis/{id}
  • The content_analysis.completed event

• Added support for the new conversation.contact_assigned event

• Added support for setting the conversation's name via POST /messages
• Added location to User in Call and Conversation types
• Added media to Message type in conversation webhook events
  • The media.vendorResourceUrl is populated for BYOT accounts

• Added support for the new contact.shared event
• Marked call.contact_assigned_with_add and call.contact_assigned_with_update events as deprecated
  • These events have been replaced with the contact.shared event and will be removed in a future version of the API

• Added a new DELETE /contentAnalysis endpoint

• Added optional transcriptionModel attribute to recordings of content in POST /contentAnalysis request payload

• Added support for custom analyzer attribute when submitting a content analysis request via POST /contentAnalysis endpoint
• Added analyzer attribute to ContentAnalysis type

• Added new API endpoints to submit and inspect content analysis requests
  • POST /contentAnalysis endpoint for submitting a content analysis request
  • GET /contentAnalysis/{id} endpoint for getting a content analysis
• Added support for the new content_analysis.completed event

• Added documentation for creating or updating a personal phonebook
• Updated description for existing /phonebooks/{id} and /phonebooks/{id}/contacts/* endpoints
  • Added support for using a user's email address as the phonebook id parameter to refer to the user's personal phonebook

• Added support for call.transcription_completed event
• Updated the documentation for text attribute of Transcript type
  • The transcript text may include LEAVE and JOIN speaker events for call recordings
• Added vendorCallIds attribute to dials attribute of parties in the Call type

• Added new manager field to user fields
  • This field is surfaced in:
    • GET /users endpoint response
    • GET /users/{id} endpoint response
    • GET /directory endpoint response
    • All user webhook events
    • All team webhook events where the user is a member of the team
    • All conversation webhook events where the user is the assigned user for the conversation or the user who sent the message
    • All call webhook events where the user is the assigned user for the call
• Added optional sendAsUser attribute to messageContent in Send Team SMS message request payload
  • When set, this field allows sending a team message on behalf of a user

• Added passthrough parameters as query string parameters in Call Insights data action requests

• Added support for call.transcript.created event
• Added new transcript attribute to call Recording type

• Added new API endpoints to manage transcripts
  • GET /transcripts endpoint for list transcripts
  • GET /transcripts/{transcriptId} endpoint for getting a transcript
  • DELETE /transcripts/{transcriptId} endpoint for deleting a transcript
  • GET /transcripts/{transcriptId}/segments endpoint for getting a transcript's segments
• Added support for the new transcript.created event

• Added support for passthrough parameters via the Inbound Conversations data action
• Added support for passthrough parameters via the Send a new SMS message and Send a new Team SMS message APIs
• Added support for passthrough parameters in conversation webhook events

• Added support for passthrough parameters via the Outbound Call and Team Call data actions
• Added support for passthrough parameters via the Redirect API

• Added support for passthrough parameters via the dial deep link route
  • Added instructions in the dial documentation
  • Added passthroughParameters field to the Call type, which applies to the call resource and call webhook event data

• Added new call, dial and message deep link routes for the Spoke Phone app
  • spoke://call/{callId} - Navigates to the details of the specified call
  • spoke://call/{callId}/insight - Navigates to the insight for the specified call
  • spoke://dial?contactNumber={contactNumber}&callerId={callerId} - Dials a contact number using a specified caller ID
  • spoke://message/sms?contactAddress={contactAddress}&companyAddress={companyAddress}&body={body} - Starts or continues an SMS conversation using the given companyAddress as the sender ID and prefills the message input with the provided body
  • spoke://message/whatsapp?contactAddress={contactAddress}&companyAddress={companyAddress}&templateName={templateName} - Starts or continues a WhatsApp conversation using the given companyAddress as the sender ID, prefilled with a message generated from the content template matching templateName

• Added new API endpoints to manage call recordings
  • GET /call/{callId}/recordings/{recordingId} endpoint for getting a call recording
  • DELETE /call/{callId}/recordings/{recordingId} endpoint for deleting a call recording
• Added new id, callId and fileSize attributes to call Recording type
  • This id can be used to delete the call recording via the DELETE endpoint above

• Added new mimeType and channels attributes to call Recording type
• Added new organisationId attribute webhook event data
• Added new spoke.precall request origin for Call Insights Data Action requests from the Spoke Phone app's incoming calls

• Added new optional parameter priority to Team Call Data Action Response Payload
• Added optional timezone attribute to parties attribute of Call type
  • The attribute will be included only if the party is of type user

• Introduced new Insights Data Action response payload to support context
  • The old response payload is now deprecated. To migrate to the new payload, return the existing payload as cards in the new payload.
• Added new spoke.callhistory request origin for Call Insights Data Action requests from the Spoke Phone app's call history
• Updated contactEmail and contactId for Call Insights Data Action request parameters for internal calls to a Spoke user

• Fixed incorrect example given for the close timer field. After 30 days should be P30D not PT30D.

• Added new optional parameter closeTimer to /messages endpoint
• Added new optional parameter closeTimer to Inbound Conversations Data Action Response Payload

• Added new optional parameter closeTimer to /teamMessages endpoint

• Added new APIs to manage webhooks
  • GET /webhooks endpoint for listing existing webhooks with pagination
  • POST /webhooks endpoint for creating a new webhook
  • GET /webhooks/{id} endpoint for getting an existing webhook
  • PUT /webhooks/{id} endpoint for updating an existing webhook
  • DELETE /webhooks/{id} endpoint for deleting an existing webhook
• Added links to example webhook event payloads under the Types of Events section

• Added new desktopEnrolledReleaseChannel attribute to UserWithAvailability type

• Added new whatsApp channel to Inbound Conversations Data Action request payload
  • companyAddress and contactAddress are updated to support the new whatsApp channel

• Added new vendor, vendorConversationId, initiatedBy, companyNumberOwner and name fields to Conversation type
  • initiatedBy and companyNumberOwner fields will only be populated for conversations created after 2 October 2023
• Added new vendorMessageId and isApiCreated fields to Message Type

• Added new claimRule to Inbound Conversations Data Action response payload

• Added new POST /teamMessages API to send messages on behalf of team using team assigned DDI

• Added new loginStatus and isDirectorySynced attributes to UserWithAvailability type

• Added documentation for the Inbound Conversations Data Action functionality
• Changed Call Group to Team inline with changes to Spoke admin and application user interfaces

• Fixed unanswered cold transfers not being returned when returnTo and returnToId parameters are provided
  • See Returning unanswered calls

• Added support for override call group display name via Call Group Data Action
• Added optional overriddenDisplayName attribute to assignedCallGroup and directoryTarget attributes of Call type
  • The attribute will be included only if the team's the display name is overridden via Call Group Data Action

• Added optional device parameters deviceId, deviceAddress and deviceExtension to Outbound Call Data Action request parameters
  • The device parameters will only be included if call is placed by a standalone SIP device
• Added support for blocking outbound calls placed by standalone SIP devices via Outbound Call Data Action
  • This overrides the flag set against the SIP device "Outbound calls allowed"

• Added new optional query parameter includeHiddenCallGroups to /directory endpoint
  • If true, return all directory entries, including hidden call groups.
  • By default, this flag is false and hidden call groups are excluded from the response
• Added new isHidden attribute to TeamWithAvailability type

• Added new assignedCallGroup attribute to Call type
  • This attribute is only populated for inbound calls, and identifies the last team directory entry a call was for.
  • Use this attribute to identify calls to a given team.
  • The attribute contains a trimmed version of the directory entry, containing id, displayName, type, and extension
• IMPORTANT CHANGE
  • The directoryTarget field on the CallGroupDataActionRequestPayload object has been deprecated in favour of assignedCallGroup.
  • The field will be removed completely in a future release. Please migrate to the new field.

• Added documentation for the Call Group Data Action functionality
• Added new extension, email and dials attributes to each party in parties attribute of Call type
  • The dials contains a list of dial attempts to the call party with a reason for each dial
• Added new joinedAt and leftAt attributes to each connection in connections attribute of Call type

• Added documentation for the new Data Action functionality
• Moved original Data Actions menu into its own section

• Added support for overriding call timeouts using twimlRedirectUrl

• Added new blocked call status and blocked outcome to Call type
  • This status is currently for outbound calls only.
  • The reason attribute on the blocked outcome identifies the reason the call was blocked. E.g. the reason is set to dataAction when the outbound call was blocked by Outbound Call Data Action.
• Added documentation for the new Data Action functionality

• Added new outcome attribute to Call type
  • This attribute is populated for all calls, and identifies the final outcome of a call
  • For inbound calls, the attribute has an optional reason field, which identifies the reason a call was abandoned or missed.
• Added new tariff attribute to Call type, and new call.tariffed event
  • This attribute is populated after the call has been tariffed.
  • Once tariffed, a call.tariffed event is emitted
  • The tariff is calculated for each connected call party on the call, based on the connection's route, duration and per-minute price
  • This field will only be populated for Spoke accounts that have the "Include Tariff in Call API" add-on enabled in their account. Contact your Spoke Account Manager to have this add-on enabled.

• Added new optional query parameter includeSuspendedUsers to /directory endpoint
  • If true, return all directory entries, including suspended users.
  • By default, this flag is false and suspended users are excluded from the response
• UserWithAvailability.status is now one of invited, active or suspended

• Added new directoryTarget attribute to Call type
  • This attribute is only populated for inbound calls, and identifies the initial directory entry a call was for.
  • Use this attribute to identify calls to a given team, user or other directory entry.
  • Webhook call events will include this attribute after the call has been processed by the Spoke telephony service. This means the earliest events in the call lifecycle to include this attribute will be call.answered / call.not_answered
  • The attribute contains a trimmed version of the directory entry, containing id, displayName, type, extension and email
• Added new waitTime and waitTimeText attributes to Call type
  • For an answered call, the waitTime is calculated as the millisecond difference between startedAt and answeredAt fields.
  • For an unanswered call, the waitTime is equivalent to the value of duration.
  • The waitTimeText field is a human readable version of the waitTime field, similar to durationText
• Added GET /directory/{entryId} endpoint.
  • Retrieves specified entry from the directory

• Added GET /phonebooks/{id}/contacts/{contactId} endpoint.
  • Retrieves specified contact from an existing phonebook

• Added new excludeEmpty query parameter to the GET /phonebooks endpoint.
  • Set this to true to exclude phonebooks that do not contain any contacts.
• Added support for optional sortOrder and contactNumber query parameters to GET /calls endpoint.

• Added support for call.started, call.answered, call.not_answered, call.hungup event
• Added support for sending a call directly to voicemail using twimlRedirectUrl

• Added new vendor and vendorCallId fields to UserWithAvailability and Call types
  • These fields include the vendor who carried the call and the vendor's call ID
  • In the case of Twilio, vendorCallId contains the callSid of the parent call
  • For the UserWithAvailability type, these fields will be populated (along with callId) when the user's availability status is busy and notAvailableRule is busyOnACall

• Added support for user.availability.updated event
• Added support for team.availability.updated event

• Added new sipAddress field to Device object for /directory endpoint

• Added new fields to trunkUsers, trunkDevices and trunkQueues which are returned by /trunks and /directory
  • displayName - Display name of the directory entry
  • type - Directory type
  • twimlRedirectUrl - Redirecting an inbound Twilio call to this target url will transfer the call to this entry

• Added trunkUsers, trunkDevices and trunkQueues to the list of entries returned by /directory endpoint

• Updated mobile field of User and UserWithAvailability objects
  • This field will now be omitted if the organisation is configured to exclude employee phone numbers from Spoke APIs

• Added new twimlRedirectUrl field to TeamWithAvailability, UserWithAvailability and Device object for
  • /directory endpoint
  • /users endpoint

• Added /directory endpoint. Lists or finds directory entries. Supports optional search parameters.
  • Lists all directory entries in the organisation. This list is equivalent to the list in Spoke application "Internal" directory view. Currently the list includes users, teams and devices. Future revisions will include trunkUsers, trunkDevices and trunkQueues
  • Optional query parameters to search the directory by extension, ivrKey or phoneNumber
• Added new fields to /users endpoint:
  • phoneNumbers - List of phone numbers of the user
  • displayName - Display name of the user
  • type - Directory type
  • availability.availabilitySummary - Describes the current availability of the user

• Added support for sending SMS Messages on behalf of a Spoke user:
  • The Spoke user must have an SMS enabled DDI
  • The from parameter allows you to specify either the user's SMS enabled DDI or their email address
  • The message will be added to a conversation (if one exists with the customer) or a new conversation will be automatically created
  • The message will appear in the user's conversations view in the Spoke application
  • The conversation.message.created event will be fired when the message is created.

• Added support for Conversation events
  • conversation.inactive
  • conversation.closed
  • conversation.message.created

• You can now create webhooks in your Spoke organisation, allowing you to listen to events as they occur within the Spoke platform. Webhooks are particularly useful for listening to call events, updating, and reacting to these in your system in near real-time.

• You can now assign trunk users and phone numbers to Spoke users when creating or updating trunk users via the /trunks/{trunkId}/trunkUsers/* endpoint.

• The content type for generating OAuth 2.0 access tokens using the client_credentials grant type now supports application/x-www-form-urlencoded, this is better aligned with RFC6749 which outlines how OAuth 2.0 tokens should be generated. The previous application/json format is now deprecated.

• Requests for PUT /phonebooks endpoints can include additional nullable fields in the body: countryIso
• Requests for PUT /phonebooks and /contacts endpoints with contact can include additional nullable fields in the body: firstName, lastName and jobTitle
• Requests for PUT/POST /trunks/{trunkId}/trunkDevices/* endpoints can include additional nullable fields in the body: description, location, model and product
• Requests for PUT/POST /trunks/{trunkId}/trunkQueues/* endpoints can include additional nullable fields in the body: description
• Requests for PUT/POST /trunks/{trunkId}/trunkUsers/* endpoints can include additional nullable fields in the body: department, description, jobTitle, location and manager

• You can now manage SIP devices, users and queues associated with your SIP Trunks. Any devices, users or queues created via this API will appear in the Internal company directory in the Spoke application. These endpoints are directly dialable from Spoke, and can optionally be associated with a Spoke User, providing full integration between Spoke and your legacy PBX.

  By integrating with the Unified Directory you can automate the process of synchronising the entries in your legacy phone system with Spoke. Platform specific integrations (e.g. Cisco UCM) will be available from Spoke Integration Partners, or you can use the following API endpoints directly:

  • Added /trunks endpoint. Lists all SIP Trunks in the organisation. Trunks must be created via the Spoke account portal and will required additional network configuration.
  • Added /trunks/{trunkId}/trunkDevices/* endpoints, with ability to list, add, update and delete Trunk Devices. Trunk devices usually represent real phones in communal areas, such as a conference phone or lunch room phone.
  • Added /trunks/{trunkId}/trunkUsers/* endpoints, with ability to list, add, update and delete Trunk Users. Trunk users usually represent the individual users in your phone system who may have soft phones or desk phones.
  • Added /trunks/{trunkId}/trunkQueues/* endpoints, with ability to list, add, update and delete Trunk Queues. Trunk queues usually represent call queues or hunt groups in your phone system.

• Added /users endpoint. Lists all Spoke users in the organisation. This list is equivalent to the list of Users in Spoke application "Internal" directory view.
  • The list includes each user's availability
  • The availability state for a given user is close to real time (lag 1-5 seconds).
  • Details about Availability statuses and reason fields are included in the API response.
• Current limitations
  • This endpoint currently supports GET /users and GET /users/{id}. Future versions may support PUT methods to enable external control of availability
  • The following properties will be exposed in a future version of this API : extensions, phone_numbers, teams

• Responses from the /calls endpoints now include additional fields:
  • isInternal: If this field is true then the call was between internal Spoke Users only.
  • contactNumber: This is the phone number of the external party to the call, irrespective of the callDirection value. This field can be used to identify a matching customer record in an external system if required.
  • companyNumber: This is the phone number of the company used for the call, and will either be the number the external party called for inbound calls, or the caller id for outbound calls.
• Added new CallSummary type which provides a set of narrative summary fields about the call, suitable for populating a call note record in an external CRM system. This object includes the following fields, and is exposed as the summary field under the Call object:
  • header: A Short header summarising the call content. This is dependent on call direction, and what is known about the caller and callee.
  • contactNumberDescription: A short description of the contactNumber (e.g "Called in from +64218880000").
  • companyNumberDescription: A short description of the companyNumber (e.g. "Call in to +6498880000").
  • outcome: A short description of the outcome of the call. This includes who answered the call, whether it was transferred and the duration of the call. (e.g. "Answered by Joseph Brealey. Transferred to Joanna Brown. Spoke for 3 minutes")
• IMPORTANT CHANGE
  • The initiator and recipient fields on the Call object have been deprecated in favour of contactNumber and companyNumber.
  • This change should simplify integrations with external CRM systems as contactNumber will always represent the phone number of the external call party.
  • These fields will be removed completely in a future release. Please migrate to the new fields.

• Responses from the /calls endpoints now include a notes type.
  • Notes can be recorded at any time after the call ends
  • A call can have multiple sets of notes recorded against it
• Added a section in the API guide relating to date/time and timestamp fields.

• Added /calls endpoint:
  • Provides the ability to retrieve calls that have been received or made by the organisation
  • Calls can be queried by time range (before, since parameters) and/or last modified timestamp (modified parameter).
  • Only returns calls that have ended (where all parties have hung up), in-flight calls are not included in the response at this time
• IMPORTANT CHANGE
  • Deprecated singular endpoints (/phonebook & /phonebook/{id}/contact) in favour of plural endpoints.
  • All future collection endpoints will be plural in form (/phonebooks, /phonebooks/{id}, /calls)
  • The current singular endpoints continue to function but will be removed in a future release. Please migrate to the new endpoints.
  • The deprecated endpoints are marked in the Deprecated section of this document
• BREAKING CHANGE
  • Replaced nextContact query string parameter with next parameter as the standard parameter for response result set paging across all endpoints

• Provides the ability to synchronise company contacts (customers, suppliers) into Spoke's external phonebook. We use this phonebook to identify incoming callers and to allow Spoke users to search and place calls. This has been modelled as follows:
  • A Phonebook is a collection of Contact(s), where a Contact is a record containing a name/phone number(s)/email addresses.
  • You can batch upload to a Phonebook (which replaces the entire contents) or upsert a single Contact into a Phonebook.
  • We support multiple external phonebooks, this allows our customers some flexibility, primarily if they are using our CSV upload functionality and have data.
• Supports authentication via OAuth 2.0 Client Credentials Flow

Spoke supports data actions as a mechanism for customizing organization specific work flows. They are useful for configuring additional call rules, such as blocking outbound calls to specific phone numbers, or overriding the caller ID shown on outbound calls.

To get started, you will need to configure a data action in the Spoke Account Portal. You will need to provide a valid, publicly routable HTTPS URL that accepts GET or POST requests with the application/json content type.

Spoke will invoke this URL with the corresponding payload when performing a data action.

For security reasons, we strongly recommend that you ensure requests to your endpoint come from Spoke. The easiest method to validate that a request was sent via Spoke is to verify the signature.

Verifying the signature

A request is considered valid based on the following conditions:

• The x-spoke-timestamp header is a valid UNIX timestamp, and represents a time sent within the last 5 minutes (using millisecond precision). This header allows the consumer to validate when a request was sent, to avoid replay attacks.
• The x-spoke-signature header is formatted as sha256=<HMAC algorithm cipher text>, and it contains the correct hash based on the hexadecimal representation of the SHA256 HMAC algorithm with the signing secret applied to <x-spoke-timestamp header value>.<request data>.
  • The calculated hash includes the timestamp to ensure that an attacker cannot modify the timestamp without also invalidating the message signature.
  • The source of <request data> depends on the HTTP method used:
    • For GET requests, it is the request URL including the query parameters
    • For POST requests, it is the raw request body

A request can be validated via the following:

const isValidSpokeRequest = (requestData: string, signingSecret: string, spokeTimestamp: number, spokeSignature: string): boolean => {

  // Determine if timestamp is valid
  const isValidTimestamp = (Date.now() - spokeTimestamp) <= 300000; // 5 x 60 x 1000
  if (!isValidTimestamp) {
    return false;
  }

  // Determine if the signature is valid
  const [algorithm, cipher] = spokeSignature.split("=");
  const body = `${spokeTimestamp}.${requestData}`

  const h = crypto.createHmac(algorithm, signingSecret);
  h.update(body);
  return h.digest("hex") === cipher;
}

Spoke will attempt to deliver Data Action events to your server once. To successfully invoke the data action, your endpoint must respond with a valid response payload within 2 seconds of the HTTP request being received.

Failure to return a response within the timeout period will not be treated as an error condition. If your endpoint does not return a response within the timeout period, the call will proceed as planned, using the original configuration for the call.

The Inbound Conversations Data Action allows you to programmatically handle the creation of a new conversation, including:

• Sending auto response messages
• Assigning one or more Spoke users to manage the conversation
• Updating the conversation name

A Conversation in Spoke is a thread of messages between a group of two or more participants. Participants can be on external channels, such as SMS or WhatsApp, or internal channels, such as user of Spoke application. External participants connect to a conversation through an SMS or WhatsApp enabled number. Internal participants connect using the Spoke application.

This Data Action is invoked when a new conversation is created from an incoming message from a participant on an external channel. A new conversation is created when a message is received from an external contact that is not already involved in an active conversation with the given company number.

Implementing this data action allows you to define which Spoke Users (if any) are responsible for managing the conversation, as well as optionally sending an auto response to the external participant. Once a conversation is created, this Data Action will not be invoked again for the contact number/company address pair, until the active conversation is closed.

Note: Spoke uses the Twilio Conversations API to support conversational messaging in the Spoke application. The Data Action(s) documented here extend the functionality of the Conversations API to enable routing, shared inbox functionality and auto response management. You can read more about Twilio's conversations API here.

Below are the settings that can be controlled via Inbound Conversations Data Action.

Auto Response

Allows an auto response message to be sent to the customer. Use this to automatically respond to the customer without waiting for a user to respond.

On top of normal auto response scenarios such as Thanks for your message, we'll be with you shortly, the auto response feature can be used for scenarios where you do not want your users handling a conversation, for example:

• Profanity in the incoming message
• Time of day
• A closed or unmonitored service channel

Routing Action

Defines whether a conversation is to be routed to Spoke users via assign or not routed via donotroute.

If a conversation is set to donotroute then no Spoke users will be assigned to the conversation. The conversation will be closed, and because no internal participants are assigned the customer will not receive any response, unless the auto response feature is also used.

Assign Users

Allows one or more Spoke users to be assigned to the conversation. This allows you to fine tune which users are added to a specific conversation. You can add more than one user, and all users can actively participate in the conversation.

Each user is identified by their email address in Spoke. Invalid emails are ignored.

Conversation Name

Allows a name to be assigned to a conversation. Use this to provide more context to your Spoke users about the conversation. The name will appear in the conversation list in the Spoke application, and will be used as the title for any push notifications that are sent to users' devices when new messages are added to the conversation.

Claim Rule

Allows a claim rule to be assigned to a conversation. Claiming a conversation requires a single team member to 'claim' ownership of the conversation. When a conversation is claimable, a 'Claim Conversation' button displays in the Spoke application. Once claimed, all other team members are removed from the conversation.

Close Timer

Allows a close timer to be set to a conversation. Use this to control how long the conversation will remain open before being automatically closed by the system. The timer is reset any time a conversation is updated, including adding new messages.

Specify the timer value in ISO8601 duration format.

Passthrough Parameters

Sets the passthrough parameters associated with the conversation.

The maximum size of passthrough parameters is 1000 bytes. If this limit is exceeded, then the passthrough parameters from the response will be discarded.

Spoke sends an HTTP POST request with the following parameters in the request body, and expects a response payload of the below shape within 2 seconds.

If the request returns a non-200 response or times out and the fallback URL is configured, Spoke will send another request to the fallback URL with the same payload.

If no response payload is returned, the conversation will proceed as planned, using the original configuration for the given company address. This means that:

• Messages to an assigned SMS enabled DDI will be routed to the assigned users
• Company numbers or addresses that are unassigned will not have any users added to the conversation, and the conversation will be automatically closed

Inbound Conversations Data Action Request Parameters

Inbound Conversations Data Action Response Payload

The Custom Insights Application Data Action allows you to programmatically enrich and customize information about a customer while you are viewing their contact card or are on a call with them in the Spoke Phone app.

Before getting started, we recommend you read the Data Action Concepts section above to familiarise yourself with the Spoke Data Action mechanism and how Twilio calls integrate with Spoke.

When a user views a contact card or is on a call, Spoke sends an HTTP GET request to the URL you have configured for the Custom Insights Application Data Action and expects a response that contains the Insight cards that will be displayed when the user views that contact’s Insights.

Spoke Phone app users can view Insights for other Spoke users from the internal directory or phonebook contacts from the external directory.

Spoke will include the following fields as query parameters when sending a contact Insights request to the configured URL for Custom Insights Application Data Action:

The request will be sent every time the user opens a contact card from the directory.

As can be seen in the request shape above, the request payloads are slightly different between internal contacts and external phonebook contacts.

Mainly, for internal contacts, the contactSource field will not be provided and the isInternal field will be true. Whereas for external phonebook contacts, the contactSource field will be included and the isInternal field will be false.

Spoke Phone app users can view Insights for calls from the call screen Insights tab.

Spoke will include the following fields as query parameters when sending a call Insights request to the configured URL:

If Spoke has identified that a call involves a contact, then the request will also include the associated contactId, contactEmail, and contactSource (contactSource only included for external phonebook contacts).

Passthrough Parameters

Any existing passthrough parameters stored against the call are included in the request. 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:

{
    "x-contactId": "HS12345",
    "x-orderId": "OR12345"
  }

The constructed Call Insights data action request will be:

https://api.example.com/insights?direction=outbound&isInternal=false&requestOrigin=spoke.call&userEmail=alice@smith.com&vendorCallId=CA1234&x-contactId=HS12345&x-orderId=OR12345

Spoke app users can view primary party's Insights for conversations from the conversation screen pop up menu or the conversation settings screen.

Spoke app users can also view any selected party's Insights for conversations from the participant pop up menu of the conversation settings screen.

Spoke will include the following fields as query parameters when sending a conversation Insights request to the configured URL:

Similar to other Data Actions, Spoke expects a response within 2 seconds. The response payload is expected to be an object containing Insight cards with optional context and preferences, as specified in the shape below.

Combining with Enlighten Insights

If your organization has Enlighten Call Insights enabled and Data Action Insights configured in the Spoke Account Portal, you can use the preferences field in the Insights response to control how Enlighten Insights are displayed alongside your Data Action Insight cards.

The following table describes the behavior of the Spoke application when these settings are configured:

Example

The following Insights Response uses the preferences field (see the schema definition above) to configure what to display in the Spoke application when both Enlighten and Data Action insights are enabled. Screenshots of each screen are shown below.

{
  "context": {
    "body": "**Peter Parker** - CEO at Stark Industries.\nLast contacted 3 days ago regarding renewal."
  },
  "cards": [
    {
      "title": "Customer Info",
      "body": "**Name**: Peter Parker\n**Company**: Stark Industries\n**Role**: CEO\n**Location**: London, UK",
      "state": "expanded",
      "thumbnail": { "icon_name": "person" }
    },
    {
      "title": "Recent Activity",
      "body": "1. Opened renewal quote email - 2 hours ago\n2. Visited [pricing page](https://example.com/pricing) - yesterday\n3. Spoke with support about billing - 3 days ago",
      "state": "expanded",
      "thumbnail": { "icon_name": "history" }
    }
  ],
  "preferences": {
    "context": {
      "preferredSource": "dataAction"
    },
    "cards": {
      "enlighten": {
        "display": "before"
      }
    }
  }
}

Pre-call (desktop only)

Only the context is shown. The context from the Insights Response is displayed as specified by preferredSource.

Call Summary (call history → select a call)

Only the context is shown. The context from the Insights Response is displayed as specified by preferredSource.

In-call (active call → Insights tab)

The context from the Insights Response is shown followed by the card list. Enlighten cards are displayed before the Data Action cards as specified by display.

Contact Insights (directory → select contact → Insights)

The context from the Insights Response is shown followed by the card list. Enlighten cards are displayed before the Data Action cards as specified by display.

Call Intelligence (call history → select a call → Insights)

The context from the Insights Response is shown followed by the card list. Enlighten cards are displayed before the Data Action cards as specified by display.

A table of Insights Data Actions that have been performed is available on the configuration page on the Spoke Account Portal and can be used to debug your Custom Insights Application.

Status Types

The status column on the table refers to the response from the configured URL. There are 3 status types:

• success
• failure
• noData

It is important to note that status does not refer to the validity of the response body.

Here are cases of each status type when they appear on the Spoke Account Portal and their scenarios when users click to view Insights and there is an error:

• The table will not be updated with a new entry if the Insights app has not been configured for an organisation

• An entry with a status of success will be added if:

  • there is a valid response or
  • the response is not valid JSON or is malformed

• An entry with a status of failed will be added if a network error is encountered

• An entry with a status of noData when the response is empty (i.e. if there is no payload) or an empty array is returned

The Outbound Call Data Action Function 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 customers 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.

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.

Spoke sends an HTTP GET request with the following query parameters, and expects a response payload of the below shape 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.

Outbound Call Data Action Request Parameters

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:

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

The constructed data action request will be:

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

Outbound Call Data Action Response Payload

The Team Call Data Action allows you to programmatically override team configuration just prior to a call being offered to a team.

Note that the data action is not invoked if the call is sent directly to the team's voicemail e.g. transferring to the team's voicemail or redirecting to Spoke via its extension with sendToVoicemail=true.

Below are the configurations that can be overridden via Team Call Data Action.

Display Name

Overrides the display name of the team the call will be offered to. This overridden name will be displayed in following areas:

• Incoming call screen for new calls, transferred calls, and rolled over calls to the team
• Incoming call and missed call notifications
• Current call screen
• Users' call history and call details on Spoke applications
• Account-wide call history and call summary on Spoke Account Portal
• Call summary and voicemail summary emails

Note: This field is ignored for internal calls.

Users

Overrides the list of users who are offered the call. This allows you to fine tune who is offered individual calls while still following standard team offer flows.

Each user is identified by their email address in Spoke. Invalid emails are ignored.

Availability rules still apply - only available users will be offered the call.

If the team's offer pattern is set to Round-robin, the call will be offered to the users in the order in which they appear in the list.

Timeout

Overrides the number of the seconds Spoke will wait for someone to answer the call before returning or forwarding the call.

The supported range of values for timeout is from 10 to 300 seconds. If the provided value falls outside the range, it will be rounded to the nearest supported value.

Next Offer Timeout

Overrides the number of the seconds Spoke will wait before offering the call to the next available user(s).

The supported range of values for nextOfferTimeout is from 5 to 60 seconds. If the provided value falls outside the range, it will be rounded to the nearest supported value.

Note : The asynchronous nature of API calls between Spoke and Twilio coupled with the overhead of setting up and tearing down call legs means that timeout values are indicative only, and the follow on action may occur some number of seconds after the timeout expires.

Priority

Overrides the priority of the call. This allows you to prioritise or deprioritise the call.

The supported range of values for priority is an integer value between 1 and 9, where 1 is the highest priority and 9 is the lowest. If the provided parameter falls outside the range, the call will be assigned a default value of 5.

Passthrough Parameters

Overrides the passthrough parameters associated with the inbound call.

Passthrough parameters can be attached to an inbound call when using Spoke's Redirect Handler.

Existing passthrough parameters are included in the POST request. If there are no existing passthrough parameters, the passthroughParameters field will be an empty object.

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.

Spoke sends an HTTP POST request with the following parameters in the request body, and expects a response payload of the below shape within 2 seconds.

If the request returns a non-200 response or times out and the fallback URL is configured, Spoke will send another request to the fallback URL with the same payload.

If no response payload is returned, the call will proceed as planned, using the original team configuration.

Team Call Data Action Request Parameters

Team Call Data Action Response Payload

A Team Call Data Action will be triggered any time a call is about to be offered to a given team. This means that it may be triggered more than one time during a call, for example:

• The team is configured with an overflow rule that routes unanswered calls to a second team
• A call is transferred by an agent to another team

In both cases above, if a Team Call Data Action is configured, two requests will be made to the configured URL. In the second request, the directoryTarget and offerConfig attributes of the request payload will be updated to reflect the new team. All other attributes will remain the same.

Data actions for teams are triggered irrespective of the source of a call. This includes:

• Direct calls to the team via a team DDI
• Calls redirected into Spoke from an external IVR such as Studio
• Calls received via the Spoke IVR
• Any actions that result in calls being offered to a team from the Spoke application, such as transfer or a user calling the team directly

The following examples illustrate when data action requests will be made during the lifecycle of a call.

Example 1 - Inbound Call with Transfer

Example 2 - Direct Call with Offer Forwarding

Example 3 - Redirect to a Team Call via API

Deep links in the Spoke Phone app allow users to route directly to specific resources or perform actions within the app by clicking a link on a web page or launching a URL from another application. These links streamline navigation, enabling users to view call history, make a call, or send messages in one click.

Deep links work across all supported platforms - Windows, MacOS, iOS and Android - and use a special spoke: URL scheme that is registered when the Spoke app is installed on the target device.

Requirement: The Spoke Phone app must be installed on the device for the deep links to work.

Supported Functionality

• Call History: View call details
• Dialing: Dial a number with a specified caller ID.
• Messaging: Initiate or continue SMS or WhatsApp conversations.

Each URL must be URI-encoded before use to ensure correct parsing.

spoke://call/{callId}

Navigates to the details of the specified call.

Parameters

• callId - The unique identifier of the call.
  • If callId is invalid or not provided, or the call does not exist, the app will redirect to the user's Call History list.

Example

spoke://call/e814fb79-3f4f-4cf3-94ed-f88a5c15cb9e

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.

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:

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

spoke://message/sms?contactAddress={contactAddress}&companyAddress={companyAddress}&body={body}

Starts or continues an SMS conversation using the given companyAddress as the sender ID and prefills the message input with the provided body.

Important: Messages are never automatically sent. The user must press the send button after reviewing or editing the prefilled content.

Parameters

• contactAddress - The +E164-formatted phone number of the contact.
  • If contactAddress is invalid or not provided, the app will navigate to the Messages tab.
  • If an SMS conversation with contactAddress exists, the user will be directed to that conversation; otherwise a new SMS conversation will be created.
• companyAddress (optional) - The +E164-formatted phone number to use as the messaging sender ID.
  • companyAddress must be a phone number from the user's list of available SMS-capable numbers.
  • If companyAddress is invalid, the user will be prompted to select a valid phone number from the list of available SMS sender IDs.
• body (optional) - The message content to prefill in the message input.
  • body should be URI-encoded to ensure correct parsing.
  • If body is not provided, the message input will be empty.

Example

spoke://message/sms?contactAddress=%2B64221112222&companyAddress=%2B14341112222&body=Hi%20Bob%2C%20this%20is%20Alice

spoke://message/whatsapp?contactAddress={contactAddress}&companyAddress={companyAddress}&templateName={templateName}

Starts or continues a WhatsApp conversation using the given companyAddress as the sender ID, prefilled with a message generated from the Twilio content template matching templateName.

Important: Messages are never automatically sent. The user must press the send button after reviewing the content generated from the matching template.

Parameters

• contactAddress - The WhatsApp address of the contact. E.g.: whatsapp:+64221112222
  • If contactAddress is invalid or not provided, the app will navigate to the Messages tab.
  • If a WhatsApp conversation with contactAddress exists, the user will be directed to that conversation; otherwise a new WhatsApp conversation will be created.
• companyAddress (optional) - The WhatsApp address to use as the messaging sender ID. E.g.: whatsapp:+14341112222
  • companyAddress must be a WhatsApp-capable number from the user's list of available WhatsApp-capable numbers.
  • If companyAddress is invalid or missing, the user will be prompted to select a valid phone number from the user's list of available WhatsApp sender IDs.
• templateName (optional) - The friendly name of the approved WhatsApp content template available.
  • The templateName must match the friendly name of the WhatsApp-approved content template on Twilio.
  • If templateName is not provided, the user will be prompted to select a template from the list of available templates.
  • If templateName is invalid, the message input will be empty.
  • For more details, refer to our WhatsApp support documentation or the Twilio Content API.

Example

spoke://message/whatsapp?contactAddress=whatsapp%3A%2B64221112222&companyAddress=whatsapp%3A%2B14341112222&templateName=WelcomeMessage

The Spoke Unified Directory is a comprehensive directory of all the users, teams and devices in your organisation. It is used to store and manage your legacy internal phone directory.