Systems and Requirements

Systems and requirements

One benefit of using the API is that you can build phone features into your applications without having to maintain your own telephony framework and services.

Before you start programming, however, you will need to set up an application webserver, define certain settings in your account, and make sure you are following certain standards.

In This Topic:

Setting Up Your Webserver

We recommend using our API’s asynchronous mode for controlling phone calls. This mode requires that you set up an application webserver, which is used to receive incoming call and message notifications, as well as in-call events.

You can use any webserver configured with a server-side scripting language, but the language that you use to process messages from our API must be able to decode JSON objects. You must also be able to reach your webserver on the Internet, and we recommend using HTTPS to protect the data included in API events—for example, phone numbers and your users’ menu selections (DTMF input).

The API also supports an optional fallback URL. If our API server cannot reach your primary webserver because it is down or is not responding, it will resend HTTP events to your fallback server, if one is configured. So, if you require back-up service for events, you must set up a second server also.

Configuring Your Application

In order to make API requests, you must define the following settings for each of your applications in your API Developer account:

  • URLs for the main and fallback webservers that you will use for your application (Main URL and Fallback URL)
  • API Key and API Password that you will use to access your resources when making API requests.

For more information, see Configuring Your Application.

Setting Up Phone Numbers and Configuring Them to Route Calls

Before you can make an API request, you will need to set up the following items in your API Developer Account.

  1. Make sure you have signed up for a API Developer account, which gives you service and developer access to our API.
  2. Add the phone numbers and extensions you will need for your application to your account.
  3. Define settings for your application in your account.
  4. Set up routes for your phone numbers. If your application will require that callers hear a menu or have the option to be routed to a queue or voicemail, you will need to set up the greetings, menus and queues for those options.

For more information, see How Do Our Features Work Together? You can also use the Configuration Checklist to make sure you have set up all of the services you will need.

HTTP Formatting

Since REST interfaces rely on the HTTP protocol, it is important to secure data and user credentials by using HTTPS and SSL. You can access the API using any platform that can make HTTPS requests. Our API supports SSL versions 2.0 and 3.0, and TLS.

Note that most programming languages include libraries for making HTTP requests. See the following sources for more information.

The API adheres to the HTTP protocol and relies on HTTP methods (POST, GET, PUT, DELETE), as well as on Content-Type and Accept headers to specify format (JSON) and encodings (UTF-8, ISO-8859-1).

If the HTTP library that you use does not allow you to specify the method or HTTP headers, these settings can be specified in the URL.

Preferred Request Format

POST /calls/
Content-Type: text/json
Accept: text/json

Alternate Format

GET /calls?method=POST&format=json

Note that objects and scripts must be provided and returned in JSON format. There are libraries for most languages that will encode and decode JSON.

Base64 Encoding

HTTP request formats also make use of Base64 encoding for encoding basic authentication credentials and uploading media files. Again, there are Base64 encoding libraries for most languages.

Learn More: