This API will first call the customer, and once they pick up the phone, it will connect them to an app (aka flow) that you have created in the system - like your landing app, or any other app that can play a greeting, have IVR etc.
A HTTP POST request to https://<your_api_key>:<your_api_token>@<subdomain>/v1/Accounts/<your_sid>/Calls/connect has to be made
- Replace
<your_api_key>and<your_api_token>with the API key and token created by you. - Replace
<your_sid>with your “Account sid” - Replace
<subdomain>with the region of your account- <subdomain> of Singapore cluster is api.exotel.com
- <subdomain> of Mumbai cluster is api.in.exotel.com
<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard
The following are the POST parameters:
| PARAMETER NAME | MANDATORY/OPTIONAL | VALUE |
|---|---|---|
| From | Mandatory | The customer phone # that will be called first In case of of mobile number, prefix the 10 digits with a 0; Ex: 09052161119. In case of landline number, prefix it with STD code; Ex: 08030752400 |
| CallerId | Mandatory | This is your Exotel Number (pick one from the 'Company Numbers' page) |
| CallType | Mandatory | "trans" - for Transactional Calls |
| Url | Mandatory | "http://my.exotel.in/exoml/start/~appid~" where ~appid~ is the identifier of the app (or flow) that you want to connect to once the 'From' number picks up the call |
| TimeLimit | Optional | The time limit (in seconds) that you want this call to last. Maximum is 4 hours. The call will be cut after this time. |
| TimeOut | Optional | The time (in seconds) to ring the called parties (both first and second call leg). Maximum is 1 minute (which, we hear is mandated by TRAI) |
| StatusCallback | Optional | When the call completes, a HTTP POST will be made to the URL mentioned with the following four parameters (This data will be passed in Message body and as multipart/form-data) : CallSid - an alpha-numeric unique identifier Status - {completed, failed, busy, no-answer} RecordingUrl - link to the call recording (if it exists) DateUpdated - time when the call state was updated last |
| CustomField | Optional | Any application specific value that will be passed back as a parameter while doing a GET request to the URL mentioned in your Passthru Applet or Greetings Applet . |
HTTP Response:
On success,
- the HTTP response status code will be 200
- the HTTP body will contain an XML such as whats given below. The "Sid" is the unique identifier of the call and will be useful to log this for future debuggability purposes.
| <?xml version="1.0" encoding="UTF-8"?> <TwilioResponse> <Call> <Sid>xxxxxxxxxxxxxxxxxxxx</Sid> <ParentCallSid/> <DateCreated>2012-08-17 12:31:49</DateCreated> <DateUpdated>2012-08-17 12:31:49</DateUpdated> <AccountSid>xxxxxxxxx</AccountSid> <To>09052161119</To> <From>09739761117</From> <PhoneNumberSid>xxxxxxx</PhoneNumberSid> <Status>in-progress</Status> <StartTime>2012-08-17 12:31:49</StartTime> <EndTime>2012-08-17 12:32:57</EndTime> <Duration></Duration> <Price></Price> <Direction>outbound-api</Direction> <AnsweredBy/> <ForwardedFrom/> <CallerName/> <RecordingUrl/> <Uri>/v1/Accounts/xxxxxxxx/Calls/xxxxxxxxxxxxxx</Uri> </Call> </TwilioResponse> |
On failure:
- the HTTP response status code will be non 200
- the HTTP body will contain an XML such as below with the details of why the request failed
| <TwilioResponse> <RestException> <Status>400</Status> <Message>Invalid Call Parameters: No 'From' specified</Message> </RestException> </TwilioResponse> |
Rate Limit:
This API is rate limited to 200 calls per minute. Once this limit has been crossed, your requests will be rejected with an HTTP 429 'Too Many Requests' code.
Sample PHP Code:
An example PHP code for this is available in GithubSample Ruby Code:
Sample code available at Github and Ruby Gem available at rubygems.org