Hoiio Open API logo Hoiio Open API

This example shows you how to make use of our IVR API to create a booking confirmation service. Visitors to your website can enter their phone number and their booking details. Then, they will receive a call to confirm or cancel their booking.

Requirements

<?php

/************
Program flow:
1. User enter booking details on web form.
2. Call out to user.
3. Read out booking details.
4. Ask user to confirm or cancel the booking.
5. Read out user's decision and hang up.

/* Hoiio developer credentials */
$hoiioAppId = "YOUR_APP_ID_HERE";
$hoiioAccessToken = "YOUR_ACCESS_TOKEN_HERE";

/* Replace with YOUR SERVER ADDRESS here for IVR notifications */
$notify_url = "https://YOUR_SERVER_ADDRESS_HERE/booking_confirmation.php";

/* IVR API URL */
$dialBlockURL = "https://secure.hoiio.com/open/ivr/start/dial";
$gatherBlockURL ="https://secure.hoiio.com/open/ivr/middle/gather";
$hangupBlockURL = "https://secure.hoiio.com/open/ivr/end/hangup";

if($_POST == null) {
    // no form submission, show order confirmation page
    show_booking_page();
} else {
    if(isset($_POST['confirm'])) {
        // user just posted the form, begin IVR flow now
        $mobile = $_POST['mobile'];
        $num_guests = $_POST['num_guests'];
        $booking_day = $_POST['booking_day'];
        $booking_time = $_POST['booking_time'];

        start_ivr_flow($mobile, $num_guests, $booking_day, $booking_time);
    } else {
        // we are already in the IVR flow, decide what to do next
        handle_ivr_flow($_POST);
    }
}

/* function to start the IVR flow after user submits booking confirmation form */
function start_ivr_flow($mobile, $num_guests, $booking_day, $booking_time) {
    global $hoiioAppId, $hoiioAccessToken, $notify_url, $dialBlockURL;

    $msg = "You have made a booking for $num_guests guests on $booking_day at $booking_time pm.";

    // use custom parameters in the notify_url to track the stage of IVR flow
    // this will be returned to you in the IVR notifications
    // next step in IVR is "gather"
    $notifications_url = $notify_url . "?state=gather";

    // prepare HTTP POST variables
    $fields = array(
                    'app_id' => urlencode($hoiioAppId),
                    'access_token' => urlencode($hoiioAccessToken),
                    'dest' => urlencode($mobile),       // call out to the user for confirmation
                    'msg' => urlencode($msg),
                    'notify_url' => urlencode($notifications_url)   // IVR notifications will be sent to this URL
    );

    $result = doPost($dialBlockURL, $fields);        // do API post for IVR Dial
    print $result;
}


/* function to decide what is the next step of IVR flow */
function handle_ivr_flow($params) {
    global $hoiioAppId, $hoiioAccessToken, $notify_url, $gatherBlockURL, $hangupBlockURL;

    if($params['call_state'] == "ongoing") {
        // only process if the call is still ongoing

        $session = $params['session'];    // retrieve session so we can control the correct IVR call
        $state = $params['state'];        // retrieve custom parameters to know which stage the IVR flow is at

        // decide what to do depending on which stage the call is at
        if($state == "gather") {
            // we have already read out the details of the booking to the user, ask user to confirm now

            $msg = "To confirm the booking, please press 1. To cancel the booking, please press 0.";

            // use custom parameters in the notify_url to track the stage of IVR flow
            // this will be returned to you in the IVR notifications
            // next step in IVR is "after_gather"
            $notifications_url = $notify_url . "?state=after_gather";

            // prepare HTTP POST variables
            $fields = array(
                            'app_id' => urlencode($hoiioAppId),
                            'access_token' => urlencode($hoiioAccessToken),
                            'session' => urlencode($session),
                            'msg' => urlencode($msg),
                            'max_digits' => urlencode("1"),    // only allow 1 digit in user input
                            'timeout' => urlencode("15"),      // allow 15s for user to input response
                            'attempts' => urlencode("2"),      // user has 2 attempts to input response
                            'notify_url' => urlencode($notifications_url)   // IVR notifications will be sent here
            );

            doPost($gatherBlockURL, $fields);        // do API post for IVR Gather
        } else if($state == "after_gather") {
            // user has just keyed in his response, read out his decision and hang up

            $digits = $params['digits'];    // retrieve user's response

            if($digits == "1")
                $msg = "Thank you for your confirmation. Good bye.";
            else
                $msg = "Your booking have been cancelled. Good bye.";

            // prepare HTTP POST variables
            $fields = array(
                            'app_id' => urlencode($hoiioAppId),
                            'access_token' => urlencode($hoiioAccessToken),
                            'session' => urlencode($session),
                            'msg' => urlencode($msg)
            );

            doPost($hangupBlockURL, $fields);        // do API post for IVR Hangup
        }
    }
}

/* generic function to do HTTP post */
function doPost($url, $fields) {
    // form up variables in the correct format for HTTP POST
    $fields_string = '';
    foreach($fields as $key => $value)
    $fields_string .= $key . '=' . $value . '&';

    $fields_string = rtrim($fields_string,'&');

    // initialize cURL
    $ch = curl_init();

    // set options for cURL
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $fields_string);

    // execute HTTP POST request
    $response = curl_exec($ch);

    // close connection
    curl_close($ch);

    return $response;
}


/* function to print HTML for order confirmation form */
function show_booking_page() {
    echo <<<CONFIRMATION
<html>
    <head>
        <title>Booking Confirmation Example</title>
    </head>
    <body>
    <h2>Booking Confirmation Example</h2>
    <form id="confirmation" action="" method="post">
        <table>
            <tr>
                <td>My mobile number (e.g. +6511111111) :</td>
                <td><input type="text" name="mobile" value=""/></td>
            </tr>
            <tr>
                <td>Number of guests:</td>
                <td><input type="text" name="num_guests" value=""/></td>
            </tr>
            <tr>
                <td>Date:</td>
                <td>
                    <select name="booking_day">
                        <option value="monday">Monday</option>
                        <option value="tuesday">Tuesday</option>
                        <option value="wednesday">Wednesday</option>
                        <option value="thursday">Thursday</option>
                        <option value="friday">Friday</option>
                        <option value="saturday">Saturday</option>
                        <option value="sunday">Sunday</option>
                    </select>
                </td>
            </tr>
            <tr>
                <td>Time:</td>
                <td>
                    <select name="booking_time">
                        <option value="6">6:00pm</option>
                        <option value="7">7:00pm</option>
                        <option value="8">8:00pm</option>
                    </select>
                </td>
            </tr>
            <tr>
                <td colspan="2"><input type="submit" value="confirm" name="confirm"/></td>
            </tr>
        </table>
    </form>
    </body>
</html>
CONFIRMATION;
}

?>

Download the source code.