PROGRAMMABLE VOICE

Intelligent Communications API

Architect and embed intelligent voice communications into your application.

Telephone Exchange Operators | 1899

Introduction

Designed for developers

Voxology’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 // send alerts, reminders, and notifications
  • Call Masking // keep personal phone numbers private between two callers
  • Call Tracking // measure the success of sales and marketing efforts
  • Click To Call // initiate phone calls through your own user interface
  • Contact Center // enable inbound and outbound call control and phone service for agents
  • Conferencing // connect two to thousands of people in a single conference
  • CRM Integration // enable and capture more customer communication
  • Interactive Voice Response (IVR) // build intelligent phone trees and dynamic menus
  • Phone Survey // create and conduct interactive phone surveys
  • Two-Factor Authentication // enhance security on your application

How It Works

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

REST API

Overview

The Voxology 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 Voxology’s REST API Methods on the API Reference.

Example Request // Make Call
curl -X POST \
 https://api.voxolo.gy/v1/Dials/Connect \
 -H 'cache-control: no-cache' \
 -H 'content-type: application/json' \
 -H 'x-api-key: YOUR_API_KEY' \
 -d '{
   "call":{
     "no":"+17145551212",
     "caller_id_no":"+19495551212"
   },
   "session_data":{
     "name":"Bob",
     "age":21
   },
   "timeout":60,
   "max_call_time":60000
}'

Call Flow Loop

Overview

Voxology’s Call Flow Loop allows you to control phone calls using our set of Call Flow Actions. When a call is initiated or received by a Voxology phone number, Voxology sends a Callback Request to the URL you designate in your Call Flow Configuration in order to fetch instructions from your server. Your callback URL may may point to a server side script which returns your JSON response, or it may also point to a static JSON file hosted with a service like Amazon S3. In both cases, your server’s response will determine what to do next with the call.

Example Callback Request // Sent To Developer’s Callback URL, From Voxology
{
    "type": "init_call",
    "app_id": "29a4a1cc-4ada-4249-a7o5-5046464f9887",
    "subaccount_id": "0",
    "call_id": "59a5e1cc-5dad-1234-r5o7-9876253c0981",
    "start_time": "2030-09-20T21:32:28.471Z",
    "direction": "inbound",
    "duration": 1002,
    "status": "live-in-progress",
    "detection": "live_person",
    "caller_no": "+19495551212",
    "caller_no_city": "Newport Beach",
    "caller_no_region": "CA",
    "caller_no_country": "US",
    "caller_no_timezone": "America/Los_Angeles",
    "api_no": "+17145551212",
    "api_no_city": "Anaheim",
    "api_no_region": "CA",
    "api_no_country": "US",
    "api_no_timezone": "America/Los_Angeles",
    "key_presses": [{ "name": "collectName", "digits": "123" }],
    "recordings": [{ "name": "recordingName", "id": "ABC123" }],
    "custom_data": null,
    "session_data": null,
    "end_time": "2016-09-20T21:32:38.144Z",
    "sip_domain": "1234-56789.accounts.sip.voxolo.gy",
    "sip_forwarded_for": "192.168.1.1"
}
Example Callback Response // Call Flow Actions Returned By Developer
{
  "actions": [
    {
      "type"   : "SAY",
      "params" : {
        "text" : "Hello, ${sessionData.firstName}. Welcome to our conference.",
        "loop" : 1
      }
    },
    {
      "type"   : "CONFERENCE",
      "params" : {
        "name" : "myConference"
      }
    },
    {
      "type"   : "SAY",
      "params" : {
        "text" : "You have left the conference. This call lasted ${callTime} milliseconds."
      }
    }
  ]
}

Call Flow Process

callback-response_loop

1. Call Initiated

Upon initiating a call from or receiving a call to a Voxology phone number that has been assigned to ‘CallFlows’, Voxology is notified with the call information.

2. Voxology Sends Request to Developer’s Server

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

3. Developer’s 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 the caller to press a key.

4. Voxology Controls the Call

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

Call Flow Actions

Voxology’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 Voxology’s Call Flow Actions and Variables on the API Reference.

Getting Started

Get started with the basics of Voxology’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 Voxology Portal Account
  • Make a Payment // After you sign up, Make a Payment in order to start making and receiving voice calls.
  • Get an API key // Finally, go to your Applications and click ‘SELECT’ to view your application’s details and get your unique API key
  • Base URL // All REST requests referenced in this documentation have the following base URL: https://api.voxolo.gy/v1

Tutorial

1. Provision A Phone Number

To receive an inbound phone call, you need to search for an available phone number, provision it, and assign it to CallFlows, using either the Portal or our REST API (instructions below).

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

curl -X GET \
  'https://api.voxolo.gy/v1/PhoneNumbers/Available?capabilities=voice,sms&search_by=prefixes&search_on=INSERT_YOUR_AREA_CODE' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY'

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 (see example below).

curl -X POST \
  https://api.voxolo.gy/v1/PhoneNumbers/CallFlows \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "phone_numbers": [
      {
        "no": "PASTE_YOUR_VOXOLOGY_NUMBER_HERE"
      }
    ]
}''

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 have your instructions for how to handle a call to that phone number. Now you need to configure your Phone Numbers Callback Configuration so that you can control the call.

2. Configure Your Phone Number’s Callback Configurations

To control calls to or from your new number, you need to tell Voxology 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-us-west-2.amazonaws.com/com.voxology.actions/docs/hello-world.json (contents below).

{
  "actions": [
    {
      "type"   : "SAY",
      "params" : {
        "text" : "Hello, world."
      }
    },
    {
      "type"   : "HANGUP"
    }
  ]
}

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

curl -X PUT \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/PASTE_YOUR_VOXOLOGY_NUMBER_HERE_URL_ENCODED' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
      "callback": {   
        "method": "GET",
        "url": "https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/hello-world.json",
        "content_type": "application/json"
      }
    }'

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 Voxology 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

You may make a call from the number that you programmed above, or from a verified Caller ID (which you can add and verify via the Portal or via the API). Either way, the phone number must have a CallFlow Configuration in order to control the call.

Once your call flow callback configuration is set, you will use the Make Call method and copy/paste the following body:

curl -X POST \
  https://api.voxolo.gy/v1/Dials/Connect \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{  
    "call":{  
      "no":"PASTE_YOUR_TO_NUMBER",
      "caller_id_no":"PASTE_YOUR_VOXOLOGY_NUMBER_HERE"
    }
}'

2. Make a Call

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

Congratulations! Now you can make calls from your Voxology 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 Voxology’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-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-MultiActionProcessing.json (contents below).

 {
   "actions": [
   {
   "type" : "SAY",
   "params" : {
     "text" : "Hello, world. Welcome to multi action processing. You can have one or more actions in the same script."
   }
 },
 {
   "type": "GOTO",
   "comment": "You use a goto to navigate in your JSON script.",
     "params": {
   "label": "MY_LABEL"
   }
 },
 {
   "type" : "SAY",
   "params" : {
     "text" : "You will not reach this part of the script because the go to action will skip this part."
   }
 },
 {
   "type": "LABEL",
   "comment": "This is a label which you would use with a GoTo",
   "name": "MY_LABEL"
 },
 {
   "type" : "SAY",
   "params" : {
     "text" : "You successfully navigated to a labeled action."
   }
 },
 {
   "type" : "HANGUP"
 }
 ]
}

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

curl -X PUT \
 'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/PASTE_YOUR_NEW_NUMBER_HERE_URL_ENCODED' \
 -H 'cache-control: no-cache' \
 -H 'content-type: application/json' \
 -H 'x-api-key: YOUR_API_KEY' \
 -d '{
     "callback": {   
       "method": "GET",
       "url": "https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-MultiActionProcessing.json",
       "content_type": "application/json"
     }
   }'

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

Voxology’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 Voxology’s API.

Prerequisites

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-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-ConditionalProcessing.json (contents below).

 {
  "actions": [
              {
      "name": "rating",
      "type": "COLLECT",
      "actions": [
        {
          "type": "SAY",
          "params": {
            "text": "Hello world. Welcome to conditional processing. Please press one on your telephone keypad."
              }
        }    
      ],
      "params": {
        "finish_on_key": "pound",
        "num_digits": 1,
        "timeout": 5000
          }
    },
    {
      "type": "IF",
      "condition": "$keyPresses == '1'",
      "then": [
      {
        "type": "SAY",
        "params": {
          "text": "You pressed 1. Thank you for following instructions."
        }
      } 
    ],
    "orElse": [
    {
      "type": "SAY",
      "params": {
        "text": "You did not press 1, and did not follow instructions."
      }
    }
   ]
  },
  {
      "type"   : "HANGUP"
    }
 ]
}

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

curl -X PUT \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/PASTE_YOUR_NEW_NUMBER_HERE_URL_ENCODED' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
      "callback": {
        "method": "GET",
        "url": "https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-ConditionalProcessing.json",
        "content_type": "application/json"
      }
    }'

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

Voxology’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 Voxology’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-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-VariableProcessing.json (contents below).

  {
  "actions": [
    {
      "type": "SESSIONDATA",
          "session_data": {
        "gender": "male",
        "age": 19,
        "isNice": true
           }
      },
      {
      "name": "rating",
      "type": "COLLECT",
      "actions": [
        {
          "type": "SAY",
          "params": {
            "text": "Hello world. Welcome to variable processing. Press 1 if you are male of over the age of 21. Otherwise press two. Then press pound."
              }
        }    
      ],
      "params": {
        "finish_on_key": "pound",
        "num_digits": 1,
        "timeout": 5000
      },
      "comments": "You may put random comments in your JSON script."
      },  
    {
      "type": "IF",
      "condition": "$keyPresses == '1' && $sessionData.gender == 'male' || $sessionData.age > 21",
      "then": [
        {
          "type": "SAY",
          "params": {
            "text": "You pressed 1, or you are over 21."
              }
        }
      ],
      "orElse": [
        {
          "type": "SAY",
          "params": {
            "text": "You did not press 1 and are not a male or are not over 21."
             }
        }
       ]
       },
        {
          "type"   : "SAY",
          "params" : {
            "text" : "We hope you enjoyed variable processing. Good bye."
              }
        },
        {
          "type"   : "HANGUP"
        }
  ]
}

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

curl -X PUT \
  'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/PASTE_YOUR_NEW_NUMBER_HERE_URL_ENCODED' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
      "callback": { 
        "method": "GET",
        "url": "https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-VariableProcessing.json",
        "content_type": "application/json"
      }
    }'

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.