Making Synchronous and Asynchronous Requests

Our API lets you initiate and control a phone call in synchronous mode or asynchronous mode. In synchronous mode, your application waits while your request is being processed and is blocked from making other API requests until the API server sends a completion response.

In asynchronous mode, the API server returns a response as soon as your request is accepted. Your application can continue initiating other requests while the first call is being executed. When the original request completes, our API server sends an HTTP event (callback) to your application. Asynchronous mode allows for better scalability of your application but it can be more complex to use and set up, requiring you to set up a webserver for your app to receive and process callbacks. While our API supports both modes for the /calls service, we recommend using asynchronous mode to control phone calls. Requests to all other services in our API must be made in synchronous mode.

About Synchronous Mode

Synchronous processing overview

With the exception of controlling phone calls, all calls made to the API are synchronous. This includes requests to create, read, update or delete resources like menus, queues and routes (call handling rules). For synchronous requests, you don’t need to specify the mode in your API call—our API will automatically treat these requests as synchronous.

With synchronous mode, the API server will respond once all call-control commands have been executed or if the system encounters an error while executing commands. Note that synchronous mode requires that the command set ends by returning control of the call to your application or ends the call (hangs up) when it completes. If the call control script doesn’t meet this requirement, our server will return an HTTP 400 Bad Request code that will include an extended error code.

Once the synchronous request completes, unless the call was terminated, your application can continue to send new commands to control the call with a PUT request to the /calls service.

About Asynchronous Mode

Asynchronous processing overview

Asynchronous mode must be explicitly enabled on a per-request basis by setting the async flag on the request URL. Any non-zero value will enable async mode.

POST /calls?async=1 HTTP/1.0

In this mode, the API server will acknowledge your request immediately with an HTTP 200 OK response and provide a UUID for the call. If an error is encountered while validating the request, our server will respond with an HTTP 400 Bad Request code that will include an extended error code.

Once the call control script ends or an error occurs, our API server will send an HTTP event to your webserver. Unless you override the URL on this particular request using the fallback_url parameter, the API server will use the Fallback URL specified when you configured your application. The HTTP Event will contain the UUID of the call that was returned when you initiated the phone call, along with other call-state data.

Once an event is received, your application must acknowledge receipt with an HTTP 200 OK code. Any other response will cause our API server to attempt to deliver the same message to your Fallback URL, if configured. If the call is still active, your application must issue the next call control script with a PUT request to the /calls service.

Note that it is possible to interleave synchronous and asynchronous requests when controlling a phone call.

Using Synchronous Versus Asynchronous Mode

While synchronous mode can be quicker to implement, consider the following:

  1. Your application will need to wait, possibly for a long time, while the call control script executes.
  2. It might not be possible to use synchronous mode in your environment. Since the API requests used to control phone calls can take several minutes to process, network equipment like firewalls and NAT devices can potentially expire their sessions before the request is complete, causing your application to fail.
  3. Synchronous mode does not support the scheduling of calls or the initiation of batch calls.

Due to its responsiveness, we recommend asynchronous mode for production applications.

Making Batch Phone Calls

With the API, you can make a single API request to initiate multiple phone calls. Phone calls are initiated based on their schedule and service rate limits.

When initiating multiple phone calls at once, the API request — a POST to the /calls resource — must be made asynchronously because phone calls will return at different times. Note that the async flag must be specified on the URL or the request will result in an error.

HTTP Events

When controlling a phone call in asynchronous mode, the API server will send an HTTP event to confirm that your initial request has completed. HTTP events are sent to the Fallback URL configured for your application, so you must set up a webserver to process these events. Using the API to receive incoming phone calls or SMS messages also requires the use of HTTP events.

Learn More: