Programmable Voice

Intelligent Communications API

 

Architect and embed intelligent voice communications into your application.

  Patrick Etzel, Co-Founder | Alpstein, Switzerland | iPhone

Introduction

Designed for developers

Shoutpoint’s Programmable Voice gives developers the keys to one of the industry’s largest and most reliable cloud communications platforms in a powerful API. The service allows you to programmatically make and receive phone calls, create call flows, modify live calls, record calls, and manage phone numbers.

Stuff you can build

Automated Message Delivery // Alerts, Reminders, Notifications
Call Masking
Call Tracking
Click To Call
Contact Center // Inbound, Outbound
Conferencing
CRM Integration
IVR // Interactive Voice Response
Phone Survey
Two-Factor Authentication

 

How It Works

Shoutpoint’s API consists of two related services, a REST API and a Callback-Response Loop:

REST API

Overview

The Shoutpoint REST API enables you to initiate, modify, and query meta data on phone calls. It also allows you to manage your account, applications, phone numbers, recordings, and callback configurations.

You can view a full list of Shoutpoint’s REST API Methods on the API Reference.

 

Example Request // Make Call

Call Flow Loop

Overview

The Shoutpoint Call Flow Loop allows you to control phone calls using our set of Call Flow Actions. When a call is initiated or received, Shoutpoint will make a request to the URL that you designate to fetch instructions from your server. Your response will determine what to do next with the call. This response can be as simple as playing a message and hanging up, or it could take the caller through a much more complicated call flow.

Example Response // Call Flow Actions

 

Call Flow Process

callback-response_loop

1. Call Initiated

Upon initiating a call from or receiving a call to a phone number assigned to /CallFlows/, Shoutpoint is notified with the call information.

 

2. Shoutpoint Sends Request to Developer Server

Shoutpoint sends a Callback Request with the call’s information to an endpoint set in the callback configuration. The request content can be JSON, XML, form post or a query string.

 

3. Developer Server Responds with Instructions

Once your server determines how to handle the call, it responds with a set of instructions to control the call. For example, play a welcome message and request to press a key.

 

4. Shoutpoint Controls the Call

Shoutpoint executes your response and modifies the phone call accordingly. Once this loop has been completed, the process starts over again with Step One. This loop continues until the phone call is over, and a final callback is sent that expects no response body.

 

Call Flow Actions

Shoutpoint’s Call Flow Actions are a set of instructions that you use to build your call flows. You can combine them in all kinds of ways to create an experience for your customers.

Basic Actions

COLLECT // Collect key presses from the caller
CONFERENCE // Place a caller into a conference
DIAL // Initiate an outbound call to another party
DETECT // Detect whether the call was picked up by a live person or voicemail box
HANGUP // Hang up the call
PAUSE // Wait to process more actions
PLAY // Play an audio file (or DTMF) to the caller
QUEUE // Add a caller to a queue
RECORD // Record the caller
REDIRECT // Direct the call to another call flow script
REJECT // Deny the call from being connected
SAY // Read text to the caller
SESSIONDATA // Insert session_data into the call
SMS // Send caller a text message
STOP // Stop executing actions
TRANSFER // Connect to another caller
WEBHOOK // Trigger a webhook to a designated URL

 

Control Flow Actions

FOREACH // Loop through an array or object
IF // Basic if-then-else conditional
GOTO // Jump to designated LABEL
LABEL // Target of GOTO

 

Variable Support

Native Constants // Many constants (like call direction, number location, etc.) are assigned as variables and available to build your call flows around
User Defined Variables // define your own variables and write them to each call via session_data

You can view a full list of Shoutpoint’s Call Flow Actions and Variables on the API Reference.

Getting Started

Get started with the basics of Shoutpoint’s Programmable Voice API.

Receive Calls

Overview

This tutorial is a step-by-step guide to setting up an inbound phone number that says “Hello, World!” and hangs up.

Prerequisites

Create an Account // Sign up for a Shoutpoint Portal Account
Make a Payment // After you sign up, Make a Payment in order to start making and receiving voice calls.
Create an Application // Once you sign up for an account, Create an Application to get your API key
Get an API key // Finally, go to your Applications and click on ‘DETAIL’ to get your unique API key

Base URL // All URLs referenced in the documentation have the same base API endpoint (https://api.shoutpoint.com/v1), which is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Tutorial

1. Provision A Phone Number

You do not need to provision a phone number for outbound calling; rather, you would simply assign a valid callerID to your CallFlows instead. Skip this step for outbound calling.

To receive an inbound phone call, you need to search for an available phone number, provision it, and assign it to CallFlows, using our REST API.

To search for an available phone number, go to List Available Phone Numbers and prepare your request (see example query below).

Once, you have made your GET request, select a phone number from the list of results and ‘copy’ it. To provision the number, go to Provision Phone Numbers, ‘paste’ the number into your request body, and assign it to CallFlows, and POST.

Now that you have provisioned your new phone number, any calls that are made to (or from) that number are routed through your application’s Call Flow. However, since you have not yet programmed your Call Flow’s Callback, we don’t know how to handle a call to that phone number. Now you need to configure your Call Flow’s Callback settings.

 

2. Configure Your Call Flow Callback

To control calls to or from your new number, you need to tell Shoutpoint where to fetch your instructions. When a call comes in, we will make a request to your server and expect you to tell us what to do next using our list of Call Flow Actions.

For your convenience, we created a sample JSON call flow script from our Call Flow Actions and posted it at the following url: https://s3.amazonaws.com/com.shoutpoint.actions/docs/hello-world.json (contents below).

To configure the callback, ‘copy’ the call flow script URL above and your new phone number and paste them into the body of the Create Call Flow Callback request and POST (see example request body below).

 

3. Call Your Number

Now you can dial the new phone number you configured. If all went well, you should hear the message “Hello, World!” followed by a hang up.

Congratulations! You are now ready to make a call from the number that you just programmed.

Make Calls

Overview

This tutorial is a step-by-step guide to making a call from your Shoutpoint phone number using the REST API.

Prerequisites

‘Receive Calls’ Tutorial // Make sure that you have completed the Receive Calls tutorial

 

Tutorial

1. Prepare your Request

To make a call from the number that you programmed above, you will use the Make Call method and copy/paste the following body:

2. Make a Call

Once you have prepared your request, POST the call. If successful, you will answer, and you should hear “Hello, World!” and then it will hang up.

Congratulations! Now you can make calls from your Shoutpoint phone numbers. Next you can point your number to your own callback URL and start building call flows using our Call Flows Actions.

Multi-Action Processing

Overview

While Shoutpoint’s API initiates a callback loop with your server during a call, we believe that you shouldn’t have to handle unnecessary callbacks! This tutorial will show you how to cut down on the chatter by responding to our callback requests with an array of actions.

Prerequisites

‘Receive Calls’ Tutorial // Make sure that you have completed the Receive Calls tutorial
‘Make Calls’ Tutorial // Make sure that you have completed the Make Calls tutorial

 

Tutorial

1. Configure Your Call Flow Callback

For your convenience, we created a sample JSON call flow script from our Call Flow Actions and posted it at the following url: https://s3.amazonaws.com/com.shoutpoint.actions/docs/Example-MultiActionProcessing.json (contents below).

To configure the callback, ‘copy’ the call flow script URL above and your new phone number and paste them into the body of the Create Call Flow Callback request and POST (example request body below).

2. Call Your Number

If all went well, you should hear several messages followed by a hang up. This script illustrates how to use multiple actions in the same Call Flow. You may use any number or combination of actions in the same Call Flow without bouncing back and forth from your server to ours.

Conditional Processing

Overview

Shoutpoint’s IF, GOTO, and LABEL actions allow you to write conditional logic into your JSON responses. This enables you to cut down on even more chatter. This tutorial is a step-by-step guide to using conditionals with Shoutpoint’s API.

Prerequisites

‘Multi-Action Processing’ Tutorial // Make sure that you have completed the Multi-Action Processing tutorial

 

Tutorial

1. Configure Your Call Flow Callback

For your convenience, we created a sample JSON call flow script from our Call Flow Actions and posted it at the following url: https://s3.amazonaws.com/com.shoutpoint.actions/docs/Example-ConditionalProcessing.json (contents below).

To configure the callback, ‘copy’ the call flow script URL above and your new phone number and paste them into the body of the Create Call Flow Callback request and POST (see example request body below).

2. Call Your Number

If all went well, you should hear a message followed by a request to press a digit on your telephone keypad. This script illustrates how to use multiple actions and conditional processing in the same Call Flow. You may use any number or combination of actions or conditional processing in the same Call Flow without bouncing back and forth from your server to ours.

Variable Processing

Overview

Shoutpoint’s Native Variables and User Defined Variables enable you to customize a call flow based on information that you know about the caller prior to the call, or information that you learn about the caller during the call. session_data may be passed into a call at any time via the the Call Flow Actions SESSIONDATA or DIAL, or the REST requests, Make Call and Session Data Injection.

This tutorial is a step-by-step guide to using variables and session_data with Shoutpoint’s API.

Prerequisites

‘Conditional Processing’ Tutorial // Make sure that you have completed the Conditional Processing tutorial

 

Tutorial

1. Configure Your Call Flow Callback

For your convenience, we created a sample JSON call flow script from our Call Flow Actions and posted it at the following url: https://s3.amazonaws.com/com.shoutpoint.actions/docs/Example-VariableProcessing.json (contents below).

To configure the callback, ‘copy’ the call flow script URL above and your new phone number and paste them into the body of the Create Call Flow Callback request and POST (see example request body below).

2. Call Your Number

If all went well, you should hear a message followed by a request to press a digit on your telephone keypad. This script illustrates how to use multiple actions, conditional processing, and variables in the same Call Flow. You may use any number or combination of actions, conditional processing, or variables in the same Call Flow without bouncing back and forth from your server to ours.

Note: The variables are being pulled from data provided by the SESSIONDATA action within the .JSON script.