Make a Call - cURL

Description

The Make Call API is used to initiate an outbound call to a PSTN number. Many companies use the make call to navigate DTMF menus and provide DTMF IVR functionality. Full API specifications for the endpoint can be found inside the Ytel API reference documentation.


Example

Sample CURL to dial out and perform an action when someone answers:

Execute the makecall API

curl -X "POST" "https://api.ytel.com/api/v3/calls/makecall.json" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -u 'AccountSID:Token' \
     --data-urlencode "From=<Your_API_number>" \
     --data-urlencode "To=<Number_To_Call>" \
     --data-urlencode "Url=<Action_URL_With_InboundXML>" \
     --data-urlencode "Method=POST" \
     --data-urlencode "StatusCallBackUrl=<Call_Status_URL>" \
     --data-urlencode "StatusCallBackMethod=POST" \

When this call is answered, a POST will be sent to the Action URL With InboundXML with all relevant call information.

Fields sent to the Action URL With InboundXML

FORM/POST PARAMETERS 
From: +1202853333
AccountSid: abc6f7f-c911-f823-fb2d-a13exyz
To: +19493562111
CallSid: 123-b030-2a42-ceb9-3eb5f555414c

A set of status posts will also be sent to the Call Status URL*.

Fields sent to the Call Status URL

Direction: outbound
To: +19493562111
Status: in-progress
AccountSid: abc6f7f-c911-f823-fb2d-a13exyz
CallSid: 123-b030-2a42-ceb9-3eb5f555414c
BilledDuration: 0
CallStartTime: 2019-01-18 17:45:22
From: +1202853333
CallInitiate: 2019-01-18 17:45:14

In-Progress: Call was answered and is ongoing

Completed: Call hung up and is no longer in process


InboundXML

When a call is answered, the Action URL With InboundXML is sent information about the call. That url should serve up an XML formatted response called InboundXML. Information about what actions can be placed inside the InboundXML can be found inside the Ytel InboundXML documentation.

Basic Example
The below basic example will tell the Ytel API to speak the phrase between the say tags when the call is answered and then hang up the call.

<Response>
  <Say>Hello. Welcome to Ytel API.</Say>
  <Hangup></Hangup>
</Response>

Basic DTMF Detect Example

The below basic example will tell the Ytel API to play the audio file between the play tags when the call is answered and then wait for a DTMF response. After a DTMF response is detected, data about the call and the DTMF response will be sent to the action url. That url will then output more InboundXML for processing. It willeither wait until it detects 4 digits or until the # key is pressed.

<Response>
  <Gather action='https://yoururl.com/m360/examples/welcome' method='POST' numDigits='4' finishOnKey='#'>
   <play>http://yoururl.com/askfordigits.mp3</play>
  </Gather>
</Response>

Basic DTMF Create Example

The below basic example will tell the Ytel API to play the audio file between the play tags when the call is answered and then wait for a DTMF response. After a DTMF response is detected, data about the call and the DTMF response will be sent to the action url. That url will then output more InboundXML for processing. It willeither wait until it detects 4 digits or until the # key is pressed.

<Response>
  <Gather action='https://yoururl.com/m360/examples/welcome' method='POST' numDigits='4' finishOnKey='#'>
    <play>http://yoururl.com/askfordigits.mp3</play>
  </Gather>
</Response>

Data Posted in the Action URL of the tag

AccountSid: abc6f7f-c911-f823-fb2d-a13exyz
Digits: 1
To: +19493562111
CallSid: 123-b030-2a42-ceb9-3eb5f555414c
From: +1202853333

The Action url will read whats passed and should output more InboundXML, as demonstrated by the PHP example response below:

<Response>
<Say>Thanks, I saw you pressed <?php echo $_GET['Digits']; ?> good bye</Say>
</Response>

Transferring a call

In the above example response shown in PHP, InboundXML outputs a say command with the digit pressed. Instead of issuing a say command, the DTMF digit could be evaluated within an if/then coniditonal statement and you could instead call out and bridge the two legs. This functionality will use the dial tag feature of InboundXML.

Dial Example

When the below InboundXML loads an outbound call will be placed to the E164 formatted number between the dial tags. The callerID supplied will be used. If no CallerID is suppled, the Ytel API number of the first leg will be used.

<Response>
    <Dial action="https://youurl.com/action.php" callerId="+12224307448" timeout="30">+19899214444</Dial>
</Response>

Upon hang up of the second leg, call information will be posted to the action url where further processing of the call can occur. The timeout value is how long the second leg of the call will ring before giving up.


Did this page help you?