Get Started with Programmable Voice

Introduction

Architect and embed intelligent voice communications into your application.

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 and transcribe 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":34
   },
   "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 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 or speech from the caller
  • CONFERENCE // Place a caller into a conference
  • DETECT // Detect whether the call was picked up by a live person or voicemail box
  • DIAL // Initiate an outbound call to another party
  • HANGUP // Hang up a 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 call
  • RECORDMESSAGE // Create a voicemail system
  • REDIRECT // Direct the call to another call flow script
  • REDIRECTEXTENSION // Direct the call to another an call flow script for an extension
  • 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
  • STREAM // Stream call audio via WebSocket Messages
  • TRANSCRIBE // Transcribe the audio of a call in real-time
  • 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

Review our Call Flow Design Guide to learn how Control Flow actions simplify your CPaaS deployment.

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 Your API key // Finally, go to your Applications and click Select to view your application’s details and get your unique API key.
  • ‘Provision Phone Number’ Tutorial // Make sure you have completed the Provision Phone Number tutorial.

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 API. If you have not already provisioned a phone number, please see our Provision Phone Number tutorial.

2. Define Your Phone Number’s HTTP Callback Configuration

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 (or CDN) 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"
    }
  ]
}

A. Go to Manage Inbound Phone Numbers page in the Portal and select the number you provisioned.

B. Click on the Callback Configuration tab.

C. Disable the Inherit Default Callback Configuration from Application toggle, and then enable the Designated a Callback URL to where Voxology will send Callback Requests toggle to display the Callback Configuration form.

D. 'Copy/Paste' https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/hello-world.json (JSON Call Flow Script) into the Callback URL field.

E. Set the Callback Method field to GET.

F. Click Save.

NOTE: You can also set the HTTP callback configuration using the Update Call Flow Configuration method.

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 an HTTP Callback Configuration in order to control the call.

Once your 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, when you answer, 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

  • ‘Provision Phone Number’ Tutorial // Make sure you have completed the Provision Phone Number tutorial.
  • ‘Receive Calls’ Tutorial // Make sure that you have completed the Receive Calls tutorial.

Tutorial

1. Define Your Phone Number’s HTTP Callback Configuration

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"
    }
  ]
}

A. Go to Manage Inbound Phone Numbers page in the Portal and select the number you provisioned.

B. Click on the Callback Configuration tab.

C. Disable the Inherit Default Callback Configuration from Application toggle, and then enable the Designated a Callback URL to where Voxology will send Callback Requests toggle to display the Callback Configuration form.

D. 'Copy/Paste' https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-MultiActionProcessing.json (JSON Call Flow Script) into the Callback URL field.

E. Set the Callback Method field to GET.

F. Click Save.

NOTE: You can also set the HTTP callback configuration using the Update Call Flow Configuration method.

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. To learn how Conditional Processing can significantly reduce your complexity, please see our Call Flow Design Guide.

Prerequisites

Tutorial

1. Define Your Phone Number’s HTTP Callback Configuration

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"
    }
  ]
}

A. Go to Manage Inbound Phone Numbers page in the Portal and select the number you provisioned.

B. Click on the Callback Configuration tab.

C. Disable the Inherit Default Callback Configuration from Application toggle, and then enable the Designated a Callback URL to where Voxology will send Callback Requests toggle to display the Callback Configuration form.

D. 'Copy/Paste' https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-ConditionalProcessing.json (JSON Call Flow Script) into the Callback URL field.

E. Set the Callback Method field to GET.

F. Click Save.

NOTE: You can also set the HTTP callback configuration using the Update Call Flow Configuration method.

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"
    }
  ]
}

A. Go to Manage Inbound Phone Numbers page in the Portal and select the number you provisioned.

B. Click on the Callback Configuration tab.

C. Disable the Inherit Default Callback Configuration from Application toggle and then enable the Designated a Callback URL to where Voxology will send Callback Requests toggle to display the Callback Configuration form.

D. 'Copy/Paste' https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-VariableProcessing.json (JSON Call Flow Script) into the Callback URL field.

E. Set the Callback Method field to GET.

F. Click Save.

NOTE: You can also set the HTTP callback configuration using the Update Call Flow Configuration method.

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.