Switchvox Developer Blog

Recommended Reading:

• Connecting to the Extend API Core Interface
• Call Creation Overview
• The switchvox.call method

To test your setup, ssh into your web server and then follow the Interact with the Extend API using Wget tutorial. By the end of that tutorial, you should have sent and received some sample XML, and you’ll be ready to continue.

For your business, you might choose to send the caller to an IVR thanking them for visiting your website, send them to a Sales Queue, or just put them in a support mailbox. What you want to do with your customers is up to you.

Below is the sample IVR (extension 808) I am using for this tutorial. I won’t go into detail on how I made this IVR; if you need help setting up your own IVR just check out the Switchvox Administrator Manual.

When you use the switchvox.call method, you have to specify which extension you will ‘dial as’ when you call the customer’s phone number. Confused? Let me explain. Normally, to make an outbound call from Switchvox you pick up a phone that is registered on Switchvox and has a Switchvox extension (say 301), and you dial a number. When that number is sent to Switchvox, it is routed based on 301’s outgoing call rules. When you are using the API to create a call, the call isn’t originating from a phone, so the system needs to know who it should dial as, so that it knows which call rules to use. To put it another way, the call has to come from somewhere!

So, I am going to create a new virtual extension (809) to be my ‘dial as’ extension for my API calls. The reason I am creating a new extension as opposed to using an existing one is that I want to limit what numbers 809 is allowed to call. Below is what the outgoing call rules looks like for extension 809. As you can see, if a customer puts in an international number or enters 911, the system won’t allow it. Also, I have created a call rule called ‘Only ext 808′. This rule is necessary because I have denied internal calls, and this rule allows the call to go to my IVR at internal extension 808.

If you have to dial a digit other than 9 for outbound calls, you need to modify the Call API settings on your ‘dial as’ extension. Otherwise leave the defaults.

Now that I have created the virtual extension 809, I need to get the account_id for this extension because switchvox.call requires it. There are a couple of easy ways to get the account_id for an extension:

1. Log into your Switchvox Admin Suite, go to Extensions -> Manage Extensions, and click the Modify button for the extension. You can get the account_id from the URL.
2. The WGET tutorial shows you how to get the account_id of an extension.
3. The Test Suite Tutorial shows you how to use the Test Suite to query the Extend API.

It doesn’t matter how you get the account_id of your extension, just make sure you write it down because you will be using it later on in this tutorial.

Now it’s time to decide how to include the cool new ‘Let Us Call You’ feature on your website. Below is a picture of what I did for this tutorial and my ‘Example Corporation.’ The red box indicates the spot where I want to put a ‘Let Us Call You’ box.

Below is picture of my ‘Let Us Call You’ box; feel free to use this same box or create your own.

For the sake of this tutorial, go ahead and create a directory on your web server called ‘letuscallyou’ and an index.html file under it that has my ‘Let Us Call You’ box on it somewhere:

.
.

    
    
    <link  href="letuscallyou/letuscallyou.css" type="text/css" rel="stylesheet"/>

<input type="text" id="letuscallyou_number" />

        


            Connecting your call.
        



.
.

This HTML references a few files that I have packaged for you in the following zip file. Download this zip file and unzip it in your new ‘letuscallyou’ directory, alongside your index.html file. The zip file will create a directory called ‘letuscallyou’ with all of the files that you need.

Download ZIP file

Below is how this directory should look.

Now you can go to the index.html Web page, type in a number, and click the green phone button. You will get a JavaScript alert with the phone number. Coming up, you’ll change the JavaScript to perform the Ajax call back to your web server and Switchvox.

Now we’ll look at the back-end PHP code that interacts with Switchvox. This back-end code requires the Switchvox PHP Client Library so you need to follow the download and install instructions found on that page. Make sure you download the library (2 PHP files) into the ‘letuscallyou’ directory that you have already created.

This is how your directory structure should look now:

Now that you have the PHP client library installed, let’s review the code that interacts with the Extend API. Go into the ‘letuscallyou’ directory and open the ‘letuscallyou.php’ file (you downloaded this in the ‘letuscallyou.zip’ file). Below is what you should see in this file.

<?
	//-get input
	$clean_number = preg_replace('/[^0-9]/','', $_GET['number'] );

	//-load php library
	require_once("SwitchvoxRequest.php");
	$request = new SwitchvoxRequest("YOUR.PBX.IP", "admin", "YOUR.ADMIN.PASSWORD");

	//-setup params
	$requestParams = array(
		'dial_first'			=> array($clean_number),
		'dial_second'			=> array ('808'),
		'dial_as_account_id' => array('1107')
	);

	//-send request and print success/fault
	$response = $request->send("switchvox.call", $requestParams);
	echo $response->getReponseStatus();
	//-Uncomment to see a dump of the returned object
	//print_r($response);
?>

Let’s break that down.

In this section, I grab the number that was passed in from the URL and clean out any characters that aren’t digits. I have to do that because the call creation API expects just digits.

	//-get input
	$clean_number = preg_replace('/[^0-9]/','', $_GET['number'] );

In this section, I include the SwitchvoxRequest.php library, and on the next line I instantiate the SwitchvoxRequest object. Make sure you change “YOUR.PBX.IP” to the IP or the hostname of your Switchvox, and make sure you change “YOUR.ADMIN.PASSWORD” to the password of your admin account.

	///-load php library
    require_once("SwitchvoxRequest.php");
	$request = new SwitchvoxRequest("YOUR.PBX.IP", "admin", "YOUR.ADMIN.PASSWORD");

In this section I create the parameters that I am going to pass to my API method. ‘dial_first’ is the number that the customer entered and Switchvox will dial that number first. When the customer picks up, Switchvox will connect the call to my ‘dial_second’ number (808, my IVR). Your ‘dial_second’ number is probably different, and depends on what you set up in Step 2. The last parameter, ‘dial_as_account_id’ is the account_id (1107) of the virtual extension (809) I got from Step 2 of this tutorial. Your account_id is probably different, so make sure you change this value in your code. For more information on parameters to the switchvox.call method, just look at the documentation in the wiki here.

	//- setup params
	$requestParams = array(
		'dial_first'			=> array($clean_number),
		'dial_second'			=> array ('808'),  //-change this
		'dial_as_account_id' => array('1107')     //-change this
	);

In the last section I call the send method on the request object and pass in the name of the core method I want to call.
The send function submits the “switchvox.call” method to Switchvox, along with the parameters, and the response object is returned. I then print out the status of the request by calling getResponseStatus. This method returns either “success” or “fault” which then gets passed back to my JavaScript Ajax call. For more information on the methods supported in the Switchvox PHP request and response object, just check out the PHP library documentation.

	//-send request and print success/fault
	$response = $request->send("switchvox.call", $requestParams);
	echo $response->getReponseStatus();

Ok now that you understand the PHP code, lets put this URL in your browser and give it a test. In your browser’s URL bar enter:

YOUR.WEBSITE.COM/letuscallyou/letuscallyou.php?number=YOUR_NUMBER

If you put in all the correct information then your phone should be ringing.

The full-fledged function makes an Ajax request to the ‘letuscallyou.php’ code and passes in the number my customer entered. It uses the prototype.js JavaScript library, which is included in my zip file and therefore is already on your machine.

If you are fine with Prototype, just name the ‘letuscallyou2′ function ‘letuscallyou’, and remove the first ‘letuscallyou’ function that only has one line.

If you use a different JavaScript library and decide to port this code example, please let us know so that we can share it with other developers. Send an email to api@switchvox.com.

function letuscallyou()
{
    $('letuscallyou_processing').show();
    $('letuscallyou_button').disabled = true;
    $('letuscallyou_number').disabled = true;
    var number = $F('letuscallyou_number');
    new Ajax.Request ('letuscallyou/letuscallyou.php',
    {
        method:'get',
        parameters: { 'number' : number },
        onSuccess:function(transport)
        {
            if( transport.responseText == 'success')
            {
                 alert('Enjoy your call.');
            }
            else
            {
                 alert('Problems calling your number. Please enter a valid 10 digit number and try again.');
            }
            $('letuscallyou_processing').hide();
            $('letuscallyou_button').disabled = false;
            $('letuscallyou_number').disabled = false;
        },
        onFailure : function()
        {
            alert('Could not call your number. Please enter a valid 10 digit number and try again.');
            $('letuscallyou_processing').hide();
            $('letuscallyou_button').disabled = false;
            $('letuscallyou_number').disabled = false;
        }
    });
}

1. To prevent abuse you might want to cache the customer’s IP in your php code and only allow 3 call attempts per minute.
2. Instead of using the switchvox.call method use the switchvox.users.call method. This way you will have a user’s password in your php code intead of the admin’s password.
3. Grab more customer information such as Name, Location, and Reason For Call. Then put that data in your customer-tracking database, and/or build a custom Switchboard panel that shows all this info to your sales agent when the call rings in. Fancy!
4. Pass back more data in the Ajax call instead of just “success” or “fault”. Example: If there are errors, iterate over the errors and pass them back as a JSON array.