Exotel Support Center

Video:

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 ( Leg 1 ) picks up the call, it connects to the number provided as ‘To’ ( Leg 2 ) or the flow (using ‘Url’).

For more information regarding the API specification, refer here.

What is the API behaviour?

Once Exotel receives an API request (POST) on Calls/connect, the platform validates the request. Post validation, Exotel initiates leg 1 (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 leg 1 of the call, a 200OK 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 instance, if 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 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 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 the figure below) primarily constitutes:

• DNS lookup time

• Connection Time

• Time-taken by the client to send the request and receive the response

• Processing time taken by the server (elaborated further)

• Network latency is 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:

*as calculated on 22nd October 2018

Note: Exotel may continue to originate a call, for up to 30 seconds in the worst case.

Based on the above historical trends and behaviour, 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 behaviour 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:

• Network latency

• Operator switch takes longer to respond back

• Transient operator/network errors

Exotel has services in place which handle 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.

Best Practices:

• 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 behaviour and response time trends detailed above.

Authored-By: Sarthak Singhal, Product Manager, Exotel