Quick-start developer guide
Kieron Lawson

Kieron Lawson

Quick-Start Developer Guide: Integrating Twilio Studio to Spoke’s Programmable Softphone

In this article we take you through every step of setting up a free Spoke Phone developer account, installing Spoke's programmable softphone, deploying Spoke's open-source functions into the Twilio Serverless environment, and finally, using Twilio Studio to send calls to a single user or groups of users in Spoke.

Prerequisites

  • A Twilio account. If you don’t have one, you can create a free Twilio account by clicking here.
  • A smartphone running the latest iOS or Android, or a computer running either MacOS or Windows.
  • A GitHub account. If you don’t have one, click here to create a free account.
  • Your Twilio Account SID and Auth Token, found in your Twilio account dashboard as shown below
  • Git, NodeJS 12 and NPM v6 installed on your computer
  • Twilio CLI installed locally on your computer
  • Twilio Serverless Plugin installed local on your computer

Getting your Twilio Account SID and Auth token

You can find your Twilio Auth Token in the Account Info pane of the Twilio Console Dashboard page. Copy down the Account SID and Auth Token as you will need them when creating your free Spoke Phone account.

Obtaining your Twilio Account SID and Auth Token
Twilio Auth Token Location

Creating A Free Spoke Phone Developer Account

Click here to create a free Spoke Phone developer account for Twilio. 

Make sure to add one or two users and setup a call group.

Once you’ve created your free Spoke Phone Developer Account, go to the Developer API page here and create a new set of Spoke Developer API credentials. Copy down the Client ID and Client Secret – you’ll need these when it comes time to deploy Spoke’s Twilio Runtime functions to your Twilio account.

Spoke Phone Developer API Credentials

Setup and deploy Spoke's Twilio runtime serverless functions

Now that your accounts are all setup, it’s time to get Spoke’s quickstart functions deployed into your Twilio account.  These functions make it easy to interconnect the Spoke Developer API with Twilio applications such as Studio and Flex, allowing you to integrate Spoke’s programmable softphone with those applications.

1. Setup and install

Checkout the twilio-runtime-spoke-api project from Spoke’s github account here, then install the required npm packages.

If you want to modify the functions to meet your own requirements, we suggest forking the project into your own github account then checking it out from there.

				
					$ git clone https://github.com/spoke-ph/twilio-runtime-spoke-api.git
$ cd twilio-runtime-spoke-api
$ npm i
				
			


2. Twilio Account Credentials

Setup your Twilio account credentials using the Twilio CLI

				
					$ twilio login
$ twilio profiles:use {YOUR_ACCOUNT}
				
			


3. Spoke Developer API Credentials

Twilio’s serverless deploy process will automatically upload any environment variables in your .env file to the Twilio service.

Update .env with the following values using your favourite editor. The values for YOUR_SPOKE_CLIENT_ID and YOUR_SPOKE_CLIENT_SECRET were provided to you when you created the Developer API in your Spoke account.

The four SPOKE_ variables defined in this file are used to obtain an OAuth 2.0 access token from the Spoke API, authenticated against your Spoke account.

				
					SPOKE_CLIENT_ID={YOUR_SPOKE_CLIENT_ID}
SPOKE_CLIENT_SECRET={YOUR_SPOKE_CLIENT_SECRET}
SPOKE_AUTH_SERVICE_URL=https://auth.spokephone.com/oauth/token
SPOKE_API_URL=https://integration.spokephone.com
				
			


4. Deploy

The deploy process will create a new Twilio Runtime service in your Spoke account called spoke-api-service. The functions and environment variables in this project will be deployed into this service.

				
					$ npm run deploy
				
			

When deployment has completed, the Twilio Serverless URL for the application will be printed to the console. This URL can be used to access the application.


5. Verify Setup

To verify your setup, login to your project in the Twilio console, and go to the Develop:Functions:Services page. Click on the spoke-api-service service, then click on Environment Variables near the bottom of the page.

Make sure that SPOKE_CLIENT_ID, SPOKE_CLIENT_SECRET, SPOKE_AUTH_SERVICE_URL, SPOKE_API_URL are correctly set, as per the screenshot below.

Create your Twilio Studio Flow

You’re now all set to get your first Twilio Studio flow up and running with Spoke! 

In this flow, we’re going to focus on two key features that you get out of box with the Spoke Directory API paired with the spoke-api-service:

  1. Making flow branching decisions in Twilio Studio based on real-time user or group availability in Spoke
  2. Using Spoke’s Directory API’s twimlRedirectUrl coupled with the optional returnTo and returnToId query parameters to send the call to Spoke and then return to the flow (to Studio) if the call goes unanswered (in Spoke).

In this flow, we’re going to welcome the caller, ask them to enter an extension number, then use the `getExtension` helper function to check whether the corresponding Spoke user is available.  If they’re available, we’ll send the call over to Spoke, and if they’re not, we’ll send the call back to the first welcome greeting.

 

1. Setup

To get started, you’ll need to create a new Studio Flow. Make sure you have a phone number attached to the flow so that the flow triggers when Twilio receives a new inbound call to the number. Add a Gather widget, and enter your welcome message.

Twilio Studio

The Gather widget will say the welcome message, then wait for the user to enter some keys.  In this quickstart, we want the caller to enter an extension number.

 

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:

Twilio Studio

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 Spoke Developer API 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.

Twilio Studio

In this case we are branching based on the status field – and will only send the call to the directory entry (in Spoke) 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 widget to add is 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.

Twilio Studio

The most basic way to use this widget is to simply set the URL field to {{widgets.get_extension.parsed.twimlRedirectUrl}}. Used in this way, if the call goes unanswered, Spoke will apply its standard business rules and either send the call to voicemail, or in the case of call groups, optionally roll the call over to another call group, voicemail, or external PSTN number.

If, instead of this you want to return the call to this flow (in Studio), add two additional parameters to the URL:

&returnTo=flow&returnToId={FLOW_ID}

These parameters instruct Spoke to return unanswered calls back to this flow, and you can continue the call by attaching further Widgets to the Return output of the Redirect widget. In this case, we’ve connected the Return output to the initial Welcome message.

 

5. Wrap up, Publish and Test

That’s it! If you’ve followed along with this tutorial, your flow should look something like this:

Twilio Studio Spoke Flow

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.

If the user doesn’t answer the call, you should be redirected back to the start of the flow and you can enter another extension.


Wrap Up and Review

Thanks for making it to the end! This quickstart guide has introduced you to creating a basic Studio flow connected to Spoke’s programmable softphone, using the Spoke Directory API and Runtime functions.

But this only scratches the surface of what you can build. Here are some other ideas to explore:

  1. Return the caller back to the initial gather menu if the extension is not found.
  2. Use other fields from getExtension such as type to branch the flow based on the type of the directory entry
  3. Use the displayName and availabilitySummary fields in a Say widget to announce the extensions availability to the caller.
  4. 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

Further Reading

Share this post

Share on facebook
Share on twitter
Share on linkedin
Share on email

Let us solve your unique problems

Get a personalized demonstration with one of our experts

Cookie Policy

This site uses cookies, find out more.

Nina

Before you go...

May I send you some key info?