About the API:
- Calls/connect API (POST) is used to connect two numbers or connect a number to a call flow.
- It connects the ‘From’ number first. Once the person at the ‘From’ end (first leg) picks up the phone, it connects to the number provided as ‘To’ (second leg) or the flow (using ‘Url’).
For more information regarding the API specification, refer here.
What is the API behavior?
Once Exotel receives an API request (POST) on Calls/connect, the platform validates the request. Post validation, Exotel initiates the first leg (connecting the ‘From’ number in the API request) of the call by sending the request to the operator switch for call origination (which indicates that we have submitted the request to the operator for initiating the call and does not mean that it is ringing at this stage). Exotel also retries if the call origination fails. All of these actions are performed synchronously.
Upon successful origination of the first leg of the call, a 200 OK HTTP response is returned.
In an event where Exotel is unable to originate the call across any route, 500 Internal Server Error or 504 Gateway Timeout error is returned.
Why is it synchronous?
This is based on the philosophy that the inability to even originate a call is an immediate failure that the caller needs to know right away to enable other workflows.
For example, a delivery agent makes a request for an outbound call, the agent would like to know if the call was placed or not.
The analogy to this API request is similar to how you make a phone call from your handset, where you would like to see if the call is originated or not as you hit the ‘call’ button. If the call origination fails, you will see it display on your handset immediately. There are scenarios when we attempt to make a call from our handset and the call does not go through, then, our tendency is to retry manually. However, In the case of this API, we do that the heavy lifting so that your call is connected.
Such reliability measures ensure call connectivity is higher and clients can take action based on the API responses.
What API response time to expect?
‘Response time’ here is the total time taken from the instance API request is triggered from your system to Exotel and your system receives a response back to that API request.
The response time (as shown in figure below) primarily constitutes:
DNS lookup time
Time-taken by the client to send the request and receive the response
Processing time-taken by the server (elaborated further)
Network latency involved at each step
By response time, we are referring to the processing time of our platform. Other factors are beyond the scope of our platform and can vary based on the location of the requesting server, network connectivity, internet lines etc..
Historically*, the API latency for Calls/connect API observed is as follows:
Average API latency (in last 6 months)
95p API Latency (in last 6 months)
99p API Latency (in last 6 months)
*as calculated on 22nd October 2018
Note: Exotel may continue to originate a call, up to 30 seconds in the worst case.
Based on the above historical trends and behavior, you can choose to set an appropriate request timeout in your application (this can vary as per your use-case, implementation, business criticality etc). However, even if a request is timed out from the client side, our platform may still originate the call as the request might have already been forwarded to the operator switch.
What can cause delays in API response?
As described in the behavior aspect of the API, Exotel will attempt to originate the call with the operator upon an API request and only then respond back (and not respond immediately upon receiving the request).
Few reasons which can cause a delay in originating the call and hence API latencies are:
Operator switch takes longer to respond back
Transient operator/network errors
Exotel has services in place which handles these scenarios by trying alternate routes which may add to the latency but ensure call connectivity is maintained. It’s a tradeoff given the unreliable nature of operator networks.
- Applications consuming this API are advised to handle the response internally in an asynchronous or non-blocking manner. This will depend on the implementation and programming language used.
- Set connection timeout and request timeout separately in your application. The time taken to establish a connection from an application client to Exotel will primarily depend on the network and location of your server. The request timeout can be set as per the API behavior and response time trends detailed above.