Knowing When to Use an Asynchronous Request

Most API commands are executed in synchronous mode. The command runs and completes, and then the API server returns either a success response or an error to your application.

The exception to this is when you use commands to control a phone call—either POST /calls or PUT /calls/UUID. Commands controlling phone calls can be run synchronously or asynchronously. They run synchronously by default, but setting the async parameter to ?async=1 makes the command run asynchronously.

What Makes a Request Asynchronous?

When you make a synchronous REST request, our API server will return a response once all of the call-control commands have been executed or an error has occurred. Typically, synchronous commands run quickly, as when sending a single SMS message or updating a simple menu object.

When you make an asynchronous request, our server will acknowledge your request as soon as it has been received and accepted (valid resource and syntax). Then, when the execution of the call-control script is complete, our server will send an HTTP success or error event to your app, using either the URL defined in your application settings, or a URL specified in your control script.

Deciding Which Mode to Use

When deciding whether to use synchronous or asynchronous mode to control phone calls, there are three factors to consider: The nature and design of your application, the duration of HTTP requests in relation to your network limitations, and whether or not you can make a webserver available to process incoming and outgoing calls.

1. Application Design

Using asynchronous mode allows you to write your application in a non-blocking way—that is, your app does not need to wait for the call-control script to run and complete before initiating additional requests. If your architecture is event driven or you are using single-threaded applications, this may improve the scalability of your application. Note, though, that using asynchronous requests in this way requires your app to process asynchronous incoming HTTP events on your application server, which can add complexity.

2. Long-lived HTTP Requests and Network Limitations

Most call-control scripts contain a set of commands that will take several seconds to complete. For example, using a script, your application might dial a phone number, wait for someone to answer the call, play an audio message, let the recipient navigate through a menu and enter a selection, or any number or combination of these steps.

The execution of a sequence like this could take several minutes, and it is possible that your network infrastructure, which might not be within your control, will not allow HTTP requests to last that long. (This is often to avoid depleting network resources; for example, firewall session timeouts or HTTP proxy timeouts.) If a network device terminates the HTTP connection while the request is in progress, your application will not receive a response from our API server.

Possible workarounds include adjusting timeout settings if you can, or you could try submitting the list of commands in separate REST requests, for example:


1 - POST /calls to create the call
[dial command]
Wait for completion
2 - PUT /calls/UUID to issue the next command
[play audio]
Wait for completion
3 - Repeat the PUT request with the next set of commands until the call completes

3. Availability of an HTTP Server for Incoming and Outgoing Calls

You will need to set up an application webserver to process HTTP events sent to your application from our API server. You will also need to have a webserver configured if you want to receive incoming phone calls or SMS messages.

However, if your application only uses outbound phone calls or SMS messages (from your account to a given phone number), you can design your app so that it uses synchronous requests only, given the technical limitations and possible impact to scalability.

In Summary

As a general rule of thumb, using synchronous requests to control phone calls is better suited for testing, provided that your network infrastructure does not interfere.

For production applications, we recommend using asynchronous mode to control calls, as it avoids scenarios where your HTTP requests can be affected by network conditions. Asynchronous mode is also likely to promote scalability, especially when controlling several phone calls at once. For more information, see Making Synchronous and Asynchronous Requests.

Learn More: