How to make IVR with HTTP OzML

In this guide you can see an example on how to make an Interactive Voice Response (IVR) with the help of your own webserver and database server using an OzML script. In addition you will see how to identify a client if he provides his PIN code. If the PIN code is correct, the customer can get information about his account.

Ozeki Phone System makes it easy to connect it to other IT applications through HTTP API. An OzML script can be placed on an own website. It can be given with the Ozeki Phone System HTTP API which website’s content the Ozeki Phone System should ask for in case of an incoming call.

http ozml
Figure 1 - HTTP OzML

Download HTTP OzML IVR example

Step 1: Install Apache, PHP and MySQL

In this example we use Wampserver development environment, because it contains Apache webserver, PHP and MySQL database server for Windows. First download Wampserver from the official website of Wampserver and then install it. After you have installed it, you need to save your PHP files to c:wampwww and you can access to your databases through MySQL console or in a web browser using PHPMyAdmin (http://localhost/phpmyadmin/) database manager.

Step 2: Create MySQL Table

In this step you can see how to make a new database and a new table in your database. In addition you will see how to insert new data into the database.

First open your PHPMyAdmin, login to the database manager (default username is root without password) and click on SQL button. Then use the create database script can be shown in Code 1 and Figure 2 to create a new database. 

CREATE DATABASE `ozekipbx`;
Code example 1 - Create database script

Figure 2 - Create a new database

After you have created a new database, click on SQL button again, and create a new table using the following script (Code 2 and Figure 3). 

CREATE TABLE `account` (
  `id` int(11) NOT NULL,
  `pincode` varchar(100) NOT NULL,
  `balance` varchar(100) NOT NULL
)
Code example 2 - Create table script

create a new table
Figure 3 - Create a new table

Use the following script to insert the user data into the account table (Code 3 and Figure 4). 

INSERT INTO `account` (`id`, `pincode`, `balance`)
VALUES (1, '1234', '3000');
Code example 3 - Add a new user account

Figure 4 - Create a new table

Step 3: Place your OzML script on your webserver

In this guide three php files are used. The first file (incomingcall.php) contains the welcome IVR menu that will be played to the client who calls your company. Code 4 shows a simple IVR menu that asks a 4 digits PIN code from the customer. he system uses the OzML UserInput command to wait these 4 digits from the user and it has a ForwardToUrl parameter which gives this imput to the selected Url. It waits 10 seconds and if there was no operation than repeat the process. You need to copy the incomingcall PHP file to c:wampwwwincomingcall.php. 

// incomingcall.php
<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <UserInput ForwardToUrl="http://localhost/dtmf_received.php" 
   		      digits="4" timeout="10" repeat="true">
    	<InitialCommands> 
       		<Speak>Please enter your 4 digits PIN code.</Speak>
		</InitialCommands>
	</UserInput>
</Response>
Code example 4 - Type a PIN code

Step 4: Verify the PIN code

Now copy the second PHP file (dtmf_received.php) to c:wampwwwdtmf_received.php that will receive and verify the PIN code. If the customer entered his 4 digits PIN code, it will be forwarded to the dtmf_received.php. This PIN code will be verified by the following PHP script that is shown in code example 5. The dtmf_received file gets DtmfDigits and make an SQL selection on this pin code in the database to get the user id. If only one row fits the selection we use the GoTo OzML command to forward the account id to dtmf_received.php file. 

// dtmf_received.php
<?php
	$dtmfdigits = $_REQUEST['DtmfDigits'];
	$sql = mysql_query('SELECT id FROM account WHERE pincode = "' . $dtmfdigits . '";');
	$row = mysql_fetch_assoc($sql);

	if(mysql_num_rows($sql) == 1) {
		$response = "<GoTo>http://localhost/members_area.php?id=
					                   " . $row['id'] . "</GoTo>";
	}
	else {
		$response = "<UserInput ForwardToUrl="http://localhost/dtmf_received.php" 
					             digits="4" timeout="10" repeat="true">";
		$response .= "<InitialCommands>";
		$response .= "<Speak>";
		$response .= "The PIN code you entered is invalid. Please give it again.";
		$response .= "Please enter your 4 digits PIN code again.";
		$response .= "</Speak>";
		$response .= "</InitialCommands>";
		$response .= "</UserInput>";
	}
?>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
	<?php
	echo $response;
	?>
</Response>
Code example 5 - Processing DTMF Signals

Step 5: Provide balance information based on the account ID

If the PIN code is not correct, the IVR speaks to the customer "The PIN code you entered is invalid. Please enter your 4 digits PIN code again". If the PIN code is correct, the account id will be forwarded to another PHP file (c:wampwwwmembers_area.php) that will query information about account balance from a database based on the account id and talk it to the customer. To transfer the client to a specified phone number you need to you use the Blindtransfer OzML command (for more OzML command description pleas visit the OzML reference book page). If the client would like to talk with a customer representative, he needs to press a button. 

// members_area.php
<?php
	$accountid = $_REQUEST['accountid'];
	$sql = mysql_query('SELECT balance FROM account WHERE id LIKE "' . $accountid . '";');
	$row = mysql_fetch_assoc($sql);
?>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
	<UserInput Timeout="5" Repeat="true"> 
		<InitialCommands> 
			<Speak>
				The pin code you entered is verified.
				Account balance, press 1.
				To call with our customer representative, press 2.
			</Speak>
		</InitialCommands> 
		<Inputs> 
			<Input Key="1"> 
				<Speak>
					<?php
					echo $row['balance'];
					?>
				</Speak>
			</Input> 
			<Input Key="2"> 
				<BlindTransfer>2000</BlindTransfer> 
			</Input> 
		</Inputs> 
	</UserInput> 
</Response>
Code example 6 - Providing account balance information

Step 6: Subscribe for incoming calls

After you have copied your files to the webserver, you need to provide the address of your PHP file that will receive the incoming calls. Click on Productivity from the upper menu bar and then select HTTP API. On the following page, click on Subscribe for events button (Figure 5).

subscribe for incoming calls
Figure 5 - Subscribe for incoming calls

On the following page click on the 'Subscribe' button (Figure 6).

click on subscribe
Figure 6 - Click on subscribe

On the following page choose an API extension that will be responsible for receiving the call and play the IVR menu. Then provide the address of your PHP file that contains the OzML script of the IVR (Figure 7).

choose an api extension and provide your php file
Figure 7 - Choose an API extension and provide your PHP file

Step 7: Forward incoming calls to the provided API Extension

After you have done with the previous installations and configurations, you need to add a new Inbound routing rule to forward the incoming calls to this IVR. On the Home page of the Ozeki Phone System XE, click on add New button belongs to the routing rules (Figure 8).

add new routing rule
Figure 8 - Add new routing rule

On the next page, first select Inbound call from the Rule scope menu. In the Source section select an outside line from the Specific outside line list on that you are waiting for the incoming calls. In the Destination section select the API extension used by the HTTP API (Figure 9).

setup inbound rule
Figure 9 - Setup inbound routing rule

Dig deeper!
People who read this also read...

More information