\n
\n
\n
Customer Alice starts a call to a company number.
\n \n
\n\n
\n
\n Request for Reception Desk
\n
\n
\n
\n
\n
Alice presses 0 for Reception Desk
\n \n
\n\n
\n
\n
Bob answers the call and talks to Alice.
\n \n
\n\n
\n
\n Request for Sales
\n
\n
\n
\n
\n
Bob transfers Alice to the Sales team
\n \n
\n\n
\n
\n
Fred answers the call and talks to Alice.
\n \n
\n\n
\n
\n
Fred hangs up the call.
\n \n
\n
\n
\n
\n Request for Customer Support
\n
\n
\n
\n
\n
Customer Alice starts a call to the Customer Support team.
\n \n
\n\n
\n
\n
No one in the Customer Support team answers.
\n \n
\n\n
\n
\n Request for Reception Desk
\n
\n
\n
\n
\n
The offer is forwarded to Reception Desk according to Customer Support's configuration.
\n \n
\n\n
\n
\n
Natty answers the call and talks to Alice.
\n \n
\n\n
\n
\n
Natty hangs up the call.
\n \n
\n
\n
\n
\n Request for Regional Sales
\n
\n
\n
\n
\n
Call from Alice is redirected to the Regional Sales team via its extension number.
\n \n
\n\n
\n
\n
No one in the Regional Sales team is available.
\n The call is returned to the originating Twilio Studio flow.
\n \n
\n\n
\n
\n Request for Global Sales
\n
\n
\n
\n
\n
The call is redirected to the Global Sales team via its extension number.
\n \n
\n\n
\n
\n
Dob answers the call and talks to Alice.
\n \n
\n\n
\n
\n
Alice hangs up the call
\n \n
\n
![\"Developer](\"./img/postman-auth.png\"\n)
\n ![\"Developer](\"./img/postman-env.png\"\n)
\n![\"Developer](\"./img/developer_api_screen.png\")
\n\nOnce 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.\n\n## Generate a Token\n\nOnce 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:\n\n| Field Name | Description |\n| --- | --- |\n| `client_id` | The client id from the Developer API |\n| `client_secret` | The client secret from the Developer API |\n| `grant_type` | Always `client_credentials` |\n\nA javascript example of this is below:\n\n```javascript\nconst response = await fetch(\"https://auth.spokephone.com/oauth/token\", {\n method: 'post',\n body: querystring.stringify({\n client_id: \"{CLIENT_ID_FROM_DEVELOPER_API}\",\n client_secret: \"{CLIENT_SECRET_FROM_DEVELOPER_API}\",\n grant_type: \"client_credentials\"\n }),\n headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n});\n\nconst { access_token } = response.json();\n```\n\n> 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`.\n\n## Make Authenticated Requests\n\nTo make authenticated API requests, you must provide a valid bearer token in an HTTP Header:\n\n`Authorization: Bearer {access_token}`\n\nOnce you have obtained an access token, you must provide this as a Bearer token for all subsequent API requests.\n\n```javascript\nconst response = await fetch(\"https://integration.spokephone.com/phonebooks\", {\n method: \"get\",\n headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${access_token}` },\n});\n```\n\n## Access Token Expiration\nAccess 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.\n\n# API Guide\n\n## Requests and Responses\nThe API is RESTful. All requests should be made over HTTPS, and accessed from `https://integration.spokephone.com`.\n\n### Requests\nMost 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.\n\n### Responses\nThe success or failure of an HTTP request is returned as a standard HTTP status code:\n\n* a `2xx` code for success\n* a `4xx` or `5xx` code for failure\n\nThe response body will always be encoded in JSON format. No other data format (e.g. XML) is supported.\n\n## Pagination\nThe Spoke Phone API uses a cursor based model for paging of large result sets.\nPaging support is available for the following endpoints:\n\n* `GET /phonebooks`\n* `GET /phonebooks/{id}/contacts`\n* `GET /calls`\n* `GET /trunks`\n* `GET /trunks/{trunkId}/trunkDevices`\n* `GET /trunks/{trunkId}/trunkQueues`\n* `GET /trunks/{trunkId}/trunkUsers`\n\nAll 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`\n\n> Example\n```http\nGET https://integration.spokephone.com/calls?limit=2 HTTP/1.1\nHost: integration.spokephone.com\n```\n> 200 Response\n```json\n{\n \"meta\": {\n \"next\": \"eyJsYXN0TW9kaWZpZWRUaW1lc3RhbXAiOjE1Njg2NzUzOTE3NTIsImNhbGxJZCI6ImE2YzVkMDgwLWQ0MWUtMTFlOS1hYzZiLWE5MTliMjAwYWFlNCIsIm9yZ2FuaXNhdGlvbklkIjoiOTQ4NzhhYzEtMDI3OS0xMWU5LWI0ZmEtNmJiYzgxMGEzZjJkIn0=\"\n },\n \"calls\": [ { ... }, { ... } ]\n}\n```\n\nEndpoints that support paging return a `meta` field in the response object, which includes a `next` token to be used in subsequent requests.\n\nSimply pass the `next` token in the query string of the next `GET` to retrieve the next page of results.\n\nIf there are no additional pages the `next` field will be empty.\n\n\n## Batch Operations\nBatch 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.\n\n## Upload Limits\nIndividual 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.\n\n## Last Modified Timestamp\nThe `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.\n\nCalling 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.\n\nThe timestamp value is a a numeric timestamp in milliseconds since the Unix epoch.\n\n## Date/Time Values\nIn general for any date/time or timestamp types, this API will provide two fields:\n\n1. `{fieldName}At`: This is an ISO8601 formatted date/time. All date/times are UTC.\n2. `{fieldName}Timestamp`: This is a numeric timestamp in milliseconds since the Unix epoch.\n\n## Postman Collection\nDownload Postman Collection: Download\n\nTo 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](#section/Authentication/Create-a-Developer-API-integration) for more details on how to create API authentication credentials).\n\nWe 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.\n\n![\"Studio](\"./img/runtime_functions/flow_with_get_extension_and_redirect.png\")
\n\nThe 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.\n\n**1. Setup**\n\nTo 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.\n\n**2. Add Run Function widget**\n\nTo 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:\n\n![\"Get](\"./img/runtime_functions/get_extension.png\")
\n\nYou will need to add one parameter to the function, called `extension`, and set the value to `{{widgets.welcome_message.Digits}}`.\n\nThe getExtension function returns the following fields by default.\n\n1. **displayName** - The display label of the directory entry\n2. **type** - The type (`userWithAvailability`, `teamWithAvailability` etc) of the directory entry\n3. **status** - The current (real time) availability of the directory entry\n4. **availabilitySummary** - Human readable availability summary\n5. **twimlRedirectUrl** - Redirect the call to this url to connect the caller to the directory entry\n\nYou can change the function to return any directory entry fields - these are documented in the [`GET /directory`](#tag/Directory) section of the developer reference.\n\n**3. Add Split Widget**\n\nThe 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.\n\n![\"Get](\"./img/runtime_functions/availability_split.png\")
\n\nIn 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]}}`.\n\nIn 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`\n\n**4. Add Redirect Widget**\n\nThe 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.\n\n![\"TwiML](\"./img/runtime_functions/redirect_widget.png\")
\n\nConfiguring this widget is simple - you just need to set the `URL` field to `{{widgets.get_extension.parsed.twimlRedirectUrl}}`\n\n**5. Publish and test your flow**\n\nThat's it! Now all you need to do is publish your flow, and test that it works.\n\nTo 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.\n\n### Review\n\nThis 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.\n\nHere are some other ideas to explore:\n\n* Return the caller back to the initial gather menu if the extension is not found\n* 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.\n* Use the optional `returnTo` and `returnToId` parameters to return the call to your flow if the call goes unanswered in Spoke.\n\n\n## Microsoft Power Automate to Dynamic 365\n\n### Overview\n\n> The Power Automate package is provided as an example set of templates to get you started with the most common\n> integration scenarios from Spoke to Dynamics 365. We expect anyone using the provided templates to accept and own the\n> operation and management of these example Microsoft Power Automate flows and ensure it is fit for purpose in the\n> environment it is installed.\n\nPower 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.\n\nPower 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.\n\nSpoke 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.\n\n[Read the DISCLAIMER before downloading the samples](https://sp-static-assets-prod.s3.amazonaws.com/sampleIntegrations/microsoft/powerAutomate/DISCLAIMER.txt)\n\n[Download the User Guide](https://sp-static-assets-prod.s3.amazonaws.com/sampleIntegrations/microsoft/powerAutomate/SpokePhone_PowerAutomate_Dynamics365_Guide.pdf)\n\n[Download the Microsoft Power Automate to Dynamics 365 samples](https://sp-static-assets-prod.s3.amazonaws.com/sampleIntegrations/microsoft/powerAutomate/SpokePhone_Dynamics365.zip)\n\n[Download the postman collection of sample Spoke webhook events](https://sp-static-assets-prod.s3.amazonaws.com/sampleIntegrations/microsoft/powerAutomate/PowerAutomate_SpokePhone_Dynamics365_webhooks.postman_collection.json)\n\n# Webhook Events\n\n## Overview\n\nSpoke 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.\n\nTo get started, you will need to configure a webhook in the Spoke [account portal](https://account.spokephone.com/developers/webhooks). Alternatively, you can use the [Webhook API](#tag/Webhooks/operation/webhookPost) 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.\n\nEvery 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.\n\n## Securing Your Webhooks\n\nOnce 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.\n\n### Verifying the signature\n\nA request is considered valid based on the following conditions:\n- 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](https://en.wikipedia.org/wiki/Replay_attack).\n- The `x-spoke-signature` header is formatted as `sha256=![\"Developer](\"./img/insights/long-cards.png\")
\n![\"Developer](\"./img/insights/data-action-config.png\")
\n![\"Developer](\"./img/insights/insights-menu-item.png\")
\n![\"Developer](\"./img/insights/in-call.png\")
\n![\"Developer](\"./img/insights/conversation-primary-1.png\")
![\"Developer](\"./img/insights/conversation-primary-2.png\")
![\"Developer](\"./img/insights/conversation-primary-3.png\")
![\"Developer](\"./img/insights/conversation-primary-4.png\")
![\"Developer](\"./img/insights/conversation-selected-1.png\")
![\"Developer](\"./img/insights/conversation-selected-2.png\")
![\"Pre-call](\"./img/insights/combinedInsightsExample/pre-call.png\")
\n![\"Call](\"./img/insights/combinedInsightsExample/call-details.png\")
\n![\"In-call](\"./img/insights/combinedInsightsExample/in-call.png\")
\n![\"Contact](\"./img/insights/combinedInsightsExample/contact.png\")
\n![\"Call](\"./img/insights/combinedInsightsExample/call-intelligence.png\")
\n![\"Developer](\"./img/insights/custom-insights-app.png\")
\n\n### Status Types\nThe `status` column on the table refers to the response from the configured URL. There are 3 status types:\n* `success`\n* `failure`\n* `noData`\n\nIt is important to note that `status` does not refer to the validity of the response body.\n\nHere 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:\n\n* #### The table will not be updated with a new entry if the Insights app has not been configured for an organisation\n\n![\"Developer](\"./img/insights/not-enabled.png\")
\n![\"Developer](\"./img/insights/not-enabled-scene.png\")
\n![\"Developer](\"./img/insights/invalid-status.png\")
\n![\"Developer](\"./img/insights/invalid.png\")
\n![\"Developer](\"./img/insights/error-status.png\")
\n![\"Developer](\"./img/insights/error.png\")
\n![\"Developer](\"./img/insights/no-data-status.png\")
\n![\"Developer](\"./img/insights/no-data.png\")
\n