Latest revision as of 13:41, 11 November 2015

1 Introduction

As a simple worked example it is possible to set up a Call Me feature on a public website which will inject a record into bxp for calling.

To see a working example, where someone will call you, please use http://www.bxpsoftware.com/call-me

2 So how does it work?

• Firstly the customer will interact with a website, WordPress website or mobile phone app.
• As part of this interaction they provide a number, and number to call.
• Code in the solution transmits those two pieces of information to the bxp API
• The bxp API receives them and logs them in a form for later processing
• As the people who will be performing the call may not necessarily have an account in bxp, the system sends an SMS to notify them of the call me.

3 Building it

3.1 The bxp parts

3.1.1 The form

Create a form. Here is a great guide. Start_Here_-_Building_your_first_form

Please take note of the Id of the form you create - this is very important. You will use that number a lot.

N.B.  Make sure that you add one simple text field for Name and one field for Phone.

3.1.2 The SMS outcome

Add an outcome to send the SMS. Form_-_What_is_an_Outcome

Main Menu > Form Management > Form - Outcome Manager > Outcome - Add > Choose your form from the previous step >

• Value: Name "Call Me - From Website" (you can change this to whatever source the Call Me is coming from e.g. Call Me - From WordPress )
• Description: Name "Call Me - From Website"
• Display Category: Incomplete
• Internal Communications
  • Internal SMS From: bxp-CallMe
  • Internal SMS To: The mobile to send to in international format eg. 353871111111. Multiple mobiles are separated by commas
  • Internal SMS Body: Using the -- field notation put in a message such as --strCDA_638_field_0_2-- on --strCDA_638_field_0_15-- [--intCDA_638_Id--]
• Scroll to the bottom and click "Add Outcome"

N.B.  The field replacements will need to change to the correct form and fields to work.  The_--_field_notation_for_bxp_Forms

3.1.3 External access

For security reasons we now need to give the outside world the ability to add records to our form.

The default setting prevents this, so we now change this to Public.

In the Public Outcome, we change this to the outcome we have just created i.e. "Call Me - From Website"

For more details please see Form_External_Options

3.1.4 Creating an API user

As all actions in bxp are audited, we need a user account to attach the audits to. For this, we create a separate user account for clarity purposes.

Main Menu > System Access Management > User Administration > Add User - Security Details Only >

• Firstname: WebsiteAPI
• Surname: WebsiteAPI
• Password: mash the keypad for lots and lots of random characters. This should be an impossible password.
• Work Contact Mobile: Put in your mobile number to remember you created this account
• Work Contact Email: Put in your email account to remember you created this account
• Is System Champion: False
• Is Approved Contact: False
• IP Range: Put in the IP address your website / service will be calling in from. You must specify a static web address.
• External System Id: WordPressAPIUsername
• External System Key: WordPressAPIPasskey

Leave everything else blank and unckecked and scroll to the bottom and hit "Create the new user"

3.1.5 Security permissions

Next, grant the user permission to the form.

Main Menu > System Access Management > Security - Content Access > Form - Single Add User by Form >

• Choose WebsiteAPI WebsiteAPI as the user
• Choose your form as the form

At this point... access your form through the bxp API from an external service.

3.2 The public parts

3.2.1 The form

So to help, we've written the code for a PHP version of this code.

<?php
//error_reporting( -1 );
//ini_set( 'display_errors', 1 );

/* ======================================================
Variable Definition
We use the query string to get two parameters
====================================================== */
$strName = $_GET['strName'];
$strPhone = $_GET['strPhone'];
$intID = 0;

/* ======================================================
The main processing part, if we have query string 
parameters, we do something
====================================================== */
if ($strPhone != '' && $strName != ''){
	
	//Processing comes from the example in 
	// http://www.bxpsoftware.com/wixi/index.php?title=Bxp_API
    //=========================================================
    //Data Setup
    //=========================================================
    $url = 'https://ww3.allnone.ie/client/client_demo/cti/userCTI_GenericEntry.asp';
	$fields_string = '';
	
    //set the extrac POST variables required
    $fields = array(
    	'user_id' 			=> urlencode('testing'),
    	'user_key' 			=> urlencode('testing'),
    	'system' 			=> urlencode('formlogging'),
    	'campaignid' 		=> urlencode('56')
    );

	//url-ify the data for the POST
	foreach($fields as $key=>$value) { $fields_string .= $key.'='.$value.'&'; }

    //url-ify the data for the POST
	$fields_string .= 'strName='.urlencode($strName).'&'; 
	$fields_string .= 'strPhone='.urlencode($strPhone).''; 

    //=========================================================
    //Process Data
    //=========================================================
    //open connection and set the url, number of POST vars, POST data, execute post
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL,		$url		);
    curl_setopt($ch, CURLOPT_POST,		1		);
    curl_setopt($ch, CURLOPT_POSTFIELDS,	$fields_string	);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 	1		);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER,	1		); 
    $result = curl_exec($ch);
    curl_close($ch);
	
?>
	Your contact has been logged with an Id of <?php echo $result; ?>
<?
}
/* ======================================================
No parameters, so we draw the form to get them
====================================================== */
else {
?>
<script type="text/javascript" language="javascript">
//========================================================================
function fn_isApproved(sText, strChars) {
	var ValidChars = strChars;
	var IsNumber=true;
	var Char;
	for (i = 0; i < sText.length && IsNumber == true; i++) { 
		Char = sText.charAt(i); 
		if (ValidChars.indexOf(Char) == -1) {
			IsNumber = false;
		}
	}
	return IsNumber;
}
//========================================================================
function fn_isNumeric(sText) {
	return fn_isApproved(sText, "0123456789.")
}
//========================================================================
function fn_CallMe(){
	// Get the current URL
	var strURL = window.location.href;
	var strName = document.getElementById('strName').value;
	var strPhone = document.getElementById('strPhone').value;
	var blAcceptable = false;
	
	//Firstly some simple validation
	if (strName == '' || strPhone == '') {
		alert ( 'Sorry but a name and phone number are needed to call you.' );
	}
	else {
		if (fn_isNumeric(strPhone) ==  false) {
			alert ('Sorry but the phone number may only contain numbers.  Please remove spaces, dots and dashes.');
		}
		else {
			if ((strName.len < 3) || (strPhone.len < 7)) {
				alert ('Sorry but the name must be at least 3 characters and the phone at least 7 digits.');
			}
			else{
				blAcceptable = true;
			}
		}
	}
	
	if (blAcceptable == true){
		//If firefox, you need to compensate for anchors
		if (strURL == null){
			strURL = document.URL;
		}
		//Append the parameters
		if (strURL.indexOf("?") > 0){
			strURL = strURL.concat ( '&strName=', strName, '&strPhone=', strPhone);
		}
		else {
			strURL = strURL.concat ( '?strName=', strName, '&strPhone=', strPhone);
		}
		//Pop the page but pass the new parameters
		window.location = strURL;
	}
}
</script>
<form name="frmClickToCall">
	Please provide your details and we'll call you <br />
	<table border="0" cellspacing="0" cellpadding="0">
		<tr>
			<td>Name<td>
			<td><input type="text" name="strName" id="strName" value="" style="width100%"></td>
		</tr>
		<tr>
			<td>Phone<td>
			<td><input type="text" name="strPhone" id="strPhone" value="" style="width100%"></td>
		</tr>
		<tr>
			<td><td>
			<td><input type="button" name="btnCallMe" id="btnCallMe" value="Call Me" style="width100%" onclick="fn_CallMe();"></td>
		</tr>
	</table>
</form>
<?
}
?>

• Lines 2 and 3 are handy for debugging PHP
• Lines 9 and 10 retrieve the Query String parameters if there are any
• The form then breaks in two 14 through 58 are where there are parameters to work on

3.2.1.1 With Parameters

• Line 24 change the client_demo to your system name
• Line 29 change this to the External System Id of the user, i.e. WordPressAPIUsername
• Line 30 change this to the External System Key of the user, i.e. WordPressAPIPasskey
• Line 32 change this to the Id of the form you created.
• Line 39 this is the field name to store the call me persons name within bxp, so change 'strName=' to be 'strCDA_X_field_Y_Z=' or whatever your form field is
• Line 40 this is the field name to store the call me phone number within bxp, so change 'strPhone=' to be 'strCDA_X_field_Y_Z=' or whatever your form field is

3.2.1.2 Without Parameters

• Lines 64 through 123 are JavaScript validation
• Lines 125 through 141 are the HTML to draw the form on screen

3.2.2 WordPress version

In order to make something like this work in your WordPress, you need to put this code into a "template".

Navigate to your WordPress instance go to wp-content > themes > your theme

Find a working existing template page. page.php should give you the default template. So copy page.php and give it a unique name such as page_template_callme.php

Edit that file and put into the first line

<?php /* Template Name: Call Me Template */ ?>

Pop the modified code from the previous section between the <div class="contentBlock" > tags.

Save and upload your template to the same folder.

Go into WordPress, create a page. From the menu on the right change the template to Call Me Template.

That should be your integration done bar appearance tweaking.