At Amazon AWS ReInvent 2016 one of the cool new features that was released was Polly, an amazingly slick synthetic voice engine. At time of writing, Polly supports a total of 47 male & female voices spread across 24 languages.

 

From the moment I saw the demo I knew I could use this to generate on the fly audio for use on Twilio.

Using AWS Polly with Twilio will allow you to make use of multiple languages, dialects and pronunciation of words. For example the word “live” in the phrases “I live in Seattle” and “Live from New York.” Polly knows that this pair of homographs are spelled the same but are pronounced quite differently. (sic) .

In this example I’m going to be using AWS Polly, Twilio TwiML (the Twilio XML based markup language) and NodeJS to produce an app that will allow you to generate on demand MP3 files which can then be nested in TwiML <Play> verbs.

Phase One: Get started by setting up the credentials needed by Polly

  1. Login to your AWS account
  2. Navigate to “Identity and Access Management”
  3. Create a new use that has programatic access (this will generate keys and a key secret).
  4. Attach the user to “AmazonPollyFullAccess” policy and finish the account creation steps.

Phase Two: Create a new NodeJS project

  1. In terminal navigate to where you keep your projects and create a new directory
    mkdir nodeJSPollyTwiML && cd nodeJSPollyTwiML
  2. Inside the directory initialise node using
    npm init
  3. The initialise script will ask you some basic questions about the application; name, keywords etc. I will leave this up to you.

Once the initialise script has finished we can install the required modules needed by NodeJS to run our application.

npm install --save aws-config aws-sdk body-parser express forms

This will install the required modules needed to build and run this app.
Now we can begin to build out this application.
Call up your favourite text editor – mine currently is Atom, which is made by the GitHub team.

Atom Screenshot

Atom allows you to keep a project directory on the left for easy navigation as well as colour coding all the files based on their git state.

The structure of the app is going to be:

├── server.js
|   ├── config.js
├── audioFiles
  • server.js will be responsible for all the application processing
  • config.js will be where the system configuration files will be stored
  • audioFiles will house the saved audio records.

Before we can write any server code we need somewhere to store our AWS credentials. Create a new file called config.js, add to this file:

var config = {
production: {
serverAddress: "https://production.domain.com",
port: 3005,
awsConfig: {
region: 'us-east-1',
maxRetries: 3,
accessKeyId: 'this is top secret',
secretAccessKey: 'this is bottom secret',
timeout: 15000
}
},
default: {
serverAddress: "https://test.domain.com",
port: 3000,
awsConfig: {
region: 'us-east-1',
maxRetries: 3,
accessKeyId: 'this is top secret test',
secretAccessKey: 'this is bottom secret test',
timeout: 15000
}
}
}

exports.get = function get(env) {
return config[env] || config.default;
}

In the configuration page we have broken out the settings into two parts; one for production systems and one for test systems (default in this case). As we are still building this app I will be working from the test environment.

Using Module exports we can now call the config file into server.js and load the credentials when we need them!

Open server.js file and load the modules needed, this should be the same as what was in package.json after npm install had completed.

To server.js we are going to add:

"use strict";

var express = require('express');
var AWS = require('aws-sdk');
var awsConfig = require('aws-config');
var path = require('path');
var bodyParser = require('body-parser');
var fs = require('fs');

// Load the config files
var config = require('./config.js').get(process.env.NODE_ENV);
AWS.config = awsConfig({
region: config.awsConfig.region,
maxRetries: config.awsConfig.maxRetries,
accessKeyId: config.awsConfig.accessKeyId,
secretAccessKey: config.awsConfig.secretAccessKey,
timeout: config.awsConfig.timeout
});

// Create a new AWS Polly object
var polly = new AWS.Polly();

var express = require('express')
var app = express()

Here we have defined that the app is to use ‘strict mode‘ when processing.

Then the script loaded all the modules and imported the configuration file.

To make use of AWS Polly a polly object is created you will see this referenced later.

Lastly an express object is created, this object will be used to handle the HTTP requests to the app.

 

Application Logic

While this application doesn’t have a lot of moving parts its important to understand whats going on.

When a HTTP Request comes in, express will route the task to a function that will engage with Polly, transmit the text and desired voice.

When Polly completes the task it will return the audio file as a data stream which is saved to disk.

Once the file has been saved to disk it can then be sent as part of the HTTP Response.

The diagram illustrates the lifecycle.

For the inbound HTTP request URL, Im going to define the structure as

/play/Carla/Hi%20Mathew.%20this%20is%20Carla%20from%20Amazon%20Web%20services.

Breaking this down, the path is comprised of ‘play‘ this refers to the Twilio Verb Play, if the application were to be built out further you could use other verbs or commands to define other paths, e.g. /host/ could generate the audio file but return the URL path of the audio file, letting the application host the file.

Next ‘Carla‘ refers to the Polly voice we want to use, as mentioned before AWS polly has a total of 47 male & female voices. Each of these voices has a name so its easy to reference which voice you want to use by calling that name.

The last part: ‘Hi%20Mathew.%20this%20is%20Carla%20from%20Amazon%20Web%20services.‘ Is the message that needs to be converted into speech. To ensure that the message is transmitted correctly you will need to URL encode the string, this converts spaces into %20, you can find more details on URL encoding here.

Add the following to server.js

// Generate an Audiofile and serve stright back to the user for use as a file stright away
app.get('/play/:voiceId/:textToConvert', function (req, res) {
var pollyCallback = function (err, data) {
if (err) console.log(err, err.stack); // an error occurred
else console.log(data); // successful response

// Generate a unique name for this audio file, the file name is: PollyVoiceTimeStamp.mp3
var filename = req.params.voiceId + (new Date).getTime() + ".mp3";
fs.writeFile('./audioFiles/'+filename, data.AudioStream, function (err) {
if (err) {
console.log('An error occurred while writing the file.');
console.log(err);
}
console.log('Finished writing the file to the filesystem ' + '/audioFiles/'+filename)

// Send the audio file
res.setHeader('content-type', 'audio/mpeg');
res.download('audioFiles/'+filename);
});
};

var pollyParameters = {
OutputFormat: 'mp3',
Text: unescape(req.params.textToConvert),
VoiceId: req.params.voiceId
};

// Make a request to AWS Polly with the text and voice needed, when the request is completed push callback to pollyCallback
polly.synthesizeSpeech(pollyParameters, pollyCallback);
})

Lets break down what this function does.

First

app.get('/play/:voiceId/:textToConvert', function (req, res) {

When a HTTP GET requests comes in that starts /play/ this function will be called. Next voiceID is the variable for the the Polly voice requested, and textToConvert the URL encoded text that needs to be converted.

To make the request to AWS Polly, the pollyParameters object needs to be populated, this consists of the chosen voice and the text to convert. MP3 has been fixed in this example.

Now the application is ready to call Polly,

polly.synthesizeSpeech(pollyParameters, pollyCallback);

here the app passes the parameters as well as a callback that will be invoked when the job is finished.

Once Polly has finished generating the audio file it will run the callback and (if successful) pass back the audio file.

The callback pollyCallback is now responsible for a two things; saving the file to disk and passing the file back to the users request.

var filename = req.params.voiceId + (new Date).getTime() + ".mp3";
fs.writeFile('./audioFiles/'+filename, data.AudioStream, function (err) {

To make sure we dont overwrite another audio file I’m using epoc timestamps to define a unique file name combined with the Polly voice used.

At the end of the callback, it will pass back to the user the audio file and a MP3 header

res.setHeader('content-type', 'audio/mpeg');
res.download('audioFiles/'+filename);

Awesome! Now we have an API that can generate synthesised speech using AWS Polly from text provided inbound.
If you build and run the application, putting in

/play/Carla/Hello%20reader.%20Thank%20you%20for%20taking%20the%20time%20to%20read%20this%20blog%20post%20and%20build%20the%20tutorial.%20I%20Hope%20it%20has%20been%20helpful%20for%20you.

You will get a MP3 file passed back in your browser!

 

Phase Three: Twilio Play

Now we have a HTTP addressable endpoint we can integrate our audio files into Twilio’s TwiML,  when Twilio makes a request to your Twilio application for TwiML you can now integrate this application into <Play> verbs. An example is:

<Response><Play>http://your.app.domain/play/Joanna/Wow.%20I%20have%20integrated%20Amazon%20Polly%20into%20my%20Twilio%20application.%20Now%20I%20can%20generate%20natural%20voices%20with%20custom%20text%20exactly%20when%20needed.%20This%20is%20amazing.</Play></Response>

When you compile your TwiML you will need to make sure that the text to speak has been url-encoded, otherwise Twilio will fail the TwiML for not being compliant.
GitHubhttps://github.com/dotmat/nodeJSPollyTwiML

Conclusion:

Integrating AWS Polly into your Twilio apps is now fast and easy. With a HTTP request you can request a desired voice convert text into an audio file which can be used with Twilio to play back to a caller / customer.

Betterments:

  1. At present time, the application is unsecured, anyone with access to your app / domain could quickly start using polly to increase your AWS spend. While Polly is very cheap ($0.000004 per character, or about $0.004 per minute of generated audio) its still something that should be addressed. I would recommend implementing some kind of auth that can check against known users database (Basic Auth for example)
  2. For common messages that you might use over and over its pointless to keep generating this for one time use, if you had a prebuilt database of common messages that your application uses, you could reference these from the API. In the GitHub repo I expanded the code to allow you to pull audio files by calling the MP3 file name.
  3. The app currently does no house keeping of audio files, each time you make a request to Polly it will generate an audio file. A good tool next would be something that deletes audio files over than a X days or weeks.

I hope this tutorial has been helpful, please reach out if you have any issues or questions!

In my last post: http://www.mathewjenkinson.co.uk/twilio-sms-conversations-using-cookies/ I used HTTP Cookies to ask multiple questions to a handset. This got me thinking, what if I could use that conversation to generate a lead in Salesforce.

For example, your at an event, ‘CloudForce’ for example 😉 and you want to ask your guests about the experience they are having as well as capture the guests phone number in a lead campaign in Salesforce ready to pick up with the lead after the event. This gives you instant feedback on how people are enjoying the event, an incoming lead stream and verified phone numbers from potential customers.

In this post, Im going to build on using Twilio cookies to populate a lead campaign in Salesforce. To initiate this setup, I want to get the interested lead to message a keyword “CloudForceEU” for example. Once the initial message comes in, I want to ask 4 questions to the lead and then pass the captured data to our Salesforce instance.

To replicate this setup you will need:

  • An account with Twilio (https://www.twilio.com/try-twilio)
  • A SMS capable number within your Account Portal.
  • A Salesforce instance where you can add custom lead fields and use Web2Lead Form generator
  • A PHP based server to host the script found on my Github.  – If your savy you can make your own in another language such as Ruby or Python 🙂

Setting up Salesforce

To begin we need to add 4 custom fields to our salesforce lead’s panel. As I am choosing to ask 4 questions to our potential lead I want to capture this information so I can get an overall feel for the event as well as capturing info about our potential lead.

To add a custom field in Salesforce go to : salesforce.com/p/setup/layout/LayoutFieldList?type=Lead&setupid=LeadFields

or:  Setup > Leads > Fields and scroll to the bottom for ‘Custom Fields’ It should look something like:

Leads Generation SalesForce

Leads Generation SalesForce

Here we want the button marked ‘New’. Following the steps, we want a new text box of no more than 150 (This is WAY more than we need as we are only gathering simple responses). Fill in the details for the new field and then continue along. I tend to add the details of the question in the description so that I know what Question1 relates to. Continue this until you have all your question fields added.

Now we are going to build our Web2Lead form and capture the ID’s needed for our SMS Script.

Navigate to: Customize > Leads > Web-To-Lead

Remove all the initial fields from the box marked ‘Selected Fields’ and then import:

  • PhoneNumber
  • Campaign
  • Question1
  • Question2
  • Question3
  • Question4

You could add first name to this setup but you would need add a name collection to the SMS conversation, while its easy to do. Its not something I will be doing in this setup.

In the end your setup should look something like:

SF Web2Lead

SF Web2Lead

Then click generate. Salesforce will spit you out some code that you could use in a webform but we are going to grab the details of this code and use it in our SMS lead tracker. The code will look something like:

 

<!– ———————————————————————- –>
<!– NOTE: Please add the following <META> element to your page <HEAD>. –>
<!– If necessary, please modify the charset parameter to specify the –>
<!– character set of your HTML page. –>
<!– ———————————————————————- –>

<META HTTP-EQUIV=”Content-type” CONTENT=”text/html; charset=UTF-8″>

<!– ———————————————————————- –>
<!– NOTE: Please add the following <FORM> element to your page. –>
<!– ———————————————————————- –>

<form action=”https://www.salesforce.com/servlet/servlet.WebToLead?encoding=UTF-8″ method=”POST”>

<input type=hidden name=”oid” value=”ABC123″>
<input type=hidden name=”retURL” value=”http://”>

<!– ———————————————————————- –>
<!– NOTE: These fields are optional debugging elements. Please uncomment –>
<!– these lines if you wish to test in debug mode. –>
<!– <input type=”hidden” name=”debug” value=1> –>
<!– <input type=”hidden” name=”debugEmail” –>
<!– value=”[email protected]”> –>
<!– ———————————————————————- –>

<label for=”phone”>Phone</label><input id=”phone” maxlength=”40″ name=”phone” size=”20″ type=”text” /><br>

<label for=”Campaign_ID”>Campaign</label><select id=”Campaign_ID” name=”Campaign_ID”><option value=””>–None–</option></select><br>

Question1:<input id=”Question1″ maxlength=”174″ name=”Question1″ size=”20″ type=”text” /><br>

Question2:<input id=”Question2″ maxlength=”174″ name=”Question2″ size=”20″ type=”text” /><br>

Question3:<input id=”Question3″ maxlength=”174″ name=”Question3″ size=”20″ type=”text” /><br>

Question4:<input id=”Question4″ maxlength=”174″ name=”Question4″ size=”20″ type=”text” /><br>

<input type=”submit” name=”submit”>

</form>

 

As you can see its quite comprehensive, what we need from this code snippet; is the form URL, formID and then the ID’s for our phone number, campaign and questions. From the script above we get

  • URL Endpoint: ‘https://www.salesforce.com/servlet/servlet.WebToLead?encoding=UTF-8’
  • FormID: ‘ABC123’
  • Phone Number: ‘phone’
  • Campaign ID : ‘Campaign_ID’
  • Question 1 : ‘Question1’
  • Question 2 : ‘Question2’
  • Question 3 : ‘Question3’
  • Question 4 : ‘Question4’

This is the data we need to plug into our SMS cookie script.

At the end of the Twilio SMS conversation, the script will bundle up the details of the conversation and HTTPS POST to the salesforce URL.

Using Twilio cookies to mange the SMS Conversation

In the last post: http://www.mathewjenkinson.co.uk/twilio-sms-conversations-using-cookies/ I used HTTP Cookies to ask multiple questions to a handset. Now we are going to do the same thing, except at the end of this conversation we are going to post the data to Salesforce. You can find a copy of the script on my Github Twilio 2 SalesforceLeads.

The full script Im going to use is:

<?php
// Load the questions we want:
$question1 = ‘Hello. Welcome to the event! We would like to ask you some questions about your experience.</Message><Message>What did you think of the venue & refreshments? 5 (Exceptional) 0 (Poor)’; // by adding the </Message><Message> you can break up the initial response into a welcome message and then question1.
$question2 = ‘And the content of the Presentations? 5 (Exceptional) 0 (Poor)’;
$question3 = ‘How likely are you to attend future Twilio events from 5 (Definitely would) to 0 (definitely would not)’;
$question4 = ‘Is there anything specific you would like to discuss with Twilio? 5 (Yes, please asks someone to call) 0 (I’ll contact you if I need anything)’;
// After we have all 4 questions we can upload to the DB and thank the user for their input
$endStatement = ‘Thanks for your time. Hope you have a fun day!’;

// If we have no cookies we need to set all the cookies to nil and ask the opening question.
if(!isset($_COOKIE[‘question1’])) {
$TwiMLResponse = $question1;
//setcookie(‘question1’, ‘nil’);
setcookie(‘event’, $_POST[‘Body’]);
setcookie(‘question1’, ‘nil’);
setcookie(‘question2’, ‘nil’);
setcookie(‘question3’, ‘nil’);
setcookie(‘question4’, ‘nil’);
}
// If Question 1 is blank we can pair the answer to question 1
elseif ($_COOKIE[‘question1’] == ‘nil’) {
setcookie(‘question1’, $_POST[‘Body’]);
$TwiMLResponse = $question2;
}
// If Question 1 is not blank we find out if question 2 is blank and move up the ladder
elseif (($_COOKIE[‘question2’] == ‘nil’)) {
setcookie(‘question2’, $_POST[‘Body’]);
$TwiMLResponse = $question3;
}
elseif (($_COOKIE[‘question3’] == ‘nil’)) {
setcookie(‘question3’, $_POST[‘Body’]);
$TwiMLResponse = $question4;
}
// After we get the response for question 4, we can assign it to the question.
// Now we have all 4 questions answered and can pass the thank you note and also make a HTTP POST to our end point
elseif (($_COOKIE[‘question4’] == ‘nil’)) {
// With the last question answered, we can reply with our end statement and POST all the data from the conversation.
$TwiMLResponse = $endStatement;
// So now we have the cookies for the event and questions 1 to 3 and the BODY tag for answer 4. Now we can make a POST request to our form with that data.

// Get cURL resource
$curl = curl_init();
// Set some options – we are passing in a useragent too here
curl_setopt_array($curl, array(
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => ‘https://www.salesforce.com/servlet/servlet.WebToLead?encoding=UTF-8’,
CURLOPT_USERAGENT => ‘TwilioSMS’,
CURLOPT_POST => 1,
// POST fields for salesforce input:
CURLOPT_POSTFIELDS => array(‘oid’ => ‘ABC123’, ‘phone’ => $_POST[‘From’], ‘Campaign_ID’ => $_COOKIE[‘event’], ‘Question1’ => $_COOKIE[‘question1’], ‘Question2’ => $_COOKIE[‘question2’], ‘Question3’ => $_COOKIE[‘question3’], ‘Question4’ => $_POST[‘Body’])

));
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);
}
header(‘content-type: text/xml’);
?>
<Response><Message><?php echo $TwiMLResponse; ?></Message></Response>

As you can see Im only use one script to manage the conversation, updating the cookies and working out where the data needs to be updated to and eventually POSTed too. As we are capturing questions about our SalesForceEU event Im going to need 4 questions:

$question1 = ‘Hello. Welcome to the event! We would like to ask you some questions about your experience.</Message><Message>What did you think of the venue & refreshments? 5 (Exceptional) 0 (Poor)’; // by adding the </Message><Message> you can break up the initial response into a welcome message and then question1.
$question2 = ‘And the content of the Presentations? 5 (Exceptional) 0 (Poor)’;
$question3 = ‘How likely are you to attend future Twilio events from 5 (Definitely would) to 0 (definitely would not)’;
$question4 = ‘Is there anything specific you would like to discuss with Twilio? 5 (Yes, please asks someone to call) 0 (I’ll contact you if I need anything)’;

As the script gets more replies from Twilio it populates the questions cookies until they are all full of data. Then we thank the user for their time, assemble the POST request and send it off to SalesForce.

CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => ‘https://www.salesforce.com/servlet/servlet.WebToLead?encoding=UTF-8’,
CURLOPT_USERAGENT => ‘TwilioSMS’,
CURLOPT_POST => 1,
// POST fields for salesforce input:
CURLOPT_POSTFIELDS => array(‘oid’ => ‘ABC123’, ‘phone’ => $_POST[‘From’], ‘Campaign_ID’ => $_COOKIE[‘event’], ‘Question1’ => $_COOKIE[‘question1’], ‘Question2’ => $_COOKIE[‘question2’], ‘Question3’ => $_COOKIE[‘question3’], ‘Question4’ => $_POST[‘Body’])

If we run a test between my phone and Salesforce we get:

Twilio2SalesForceSMS

Twilio2SalesForceSMS

 

and in SalesForce:

SalesForce Leed Capture from SMS

SalesForce Leed Capture from SMS

 

As you can see this opens up lots of possibilities of lead capture and accurate number sourcing from events. You can even have a campaign manager back at HQ reaching back out to leads while they are still at the event.

 

So for months of my development I’ve wanted to host and use a GitLab Droplet on Digital Ocean (https://www.digitalocean.com/?refcode=8dc34df963c1). Using the server works great for all my projects bar, ANYTHING xCode! The hours spent screaming at a bit of software “… But the Password is correct you stupid f*$ker, AHHH!!!!”

Up to this point, I had taken to using Xcode to locally manage the git repo for a particular project, which worked well but didn’t allow me to swap machines, pass code to friends or do anything close to what GitLab can to in term of backup and team management.

Eventually I came up with the idea of initialising the Git settings for a project and was going to push all the updated code / changes to GitLab using terminal. Ie, write all the code / project in Xcode, then close Xcode, launch terminal and then push from terminal to GitLab. But then, after I had setup a project directory, added the information needed to connect it to my git: “git init” and then “git remote add origin [email protected]:MyUserName/GitRepo.git” and had done the initial commit and push.

I went into Xcode, created a new project, navigated to the same directory and Xcode proudly told me that a git repo was already in use! See screenshot:

Git Repo Already Exists

Git Repo Already Exists

Clicking ok, and moving on with the rest of the project settings I can now push, commit and update all information FROM Xcode to my GitLab projects.

I hope this helps lots of people who struggle with GitLab / Xcode interrogations, from looking at forums and how-to guides. It seems a lot of people current struggle.

One of the coolest things about having your own phone number with Twilio (Twilio.com). Is that you can do some very nifty things with it.

For example, if you need a conference room setup with a text message you can forward to your friends, you can configure this in a PHP script quite easily, we can even get the script to respond to your request with details about the number to ring and the pin code.

If you haven’t already done so, head over to Twilio (Twilio.com) an sign up at: Try-Twilio This will provision you a Twilio number that you can call into and interact with.

Once we have a number lets build a script that can respond to our SMS message, generate the conference room pin and then respond back with the details of our conference room.

<?php

// Incoming Voice number thats paired with this setup – used for voice Conferences etc.
$voiceNumber = “+1…”;

// Get the Variables from the HTTP POST, We want to know the BODY and the FROM so we can authorise and action the request.

$fromPhoneNumber = $_POST[“From”];
$messageBody = $_POST[“Body”];

// Check the phone number is on our authorised list if so action the SMS request.

// As this grows I want to put the numbers into an authorised DB and make a DB request regarding this.
// As this minute we are just going to look up against authorised number just in the IF field.

if ($fromPhoneNumber == “+1…” or “+44…”) // This is the list of authorised numbers that can make conf rooms.

{

// If the number is authorised then we are going to look at the body for what we need to make / do.

if ($messageBody == “Conference” or “Conf”)
{
// If the body is Conference we want to generate a 4 digit pin number and then generate a SMS message that can be
// forwarded out to the participants.

// The idea is that this script will reply with
// “A Conference has been setup, please call XYZ Number press option X and enter pin abcd”

$confPin = rand(1000, 9999); // Generate a random pin number
$TwiMLResponse = “<Message>Conference Room Details:\r\nPhone Number: ” . $voiceNumber . “\r\nConference Pin: ” . $confPin. “</Message>”;
}
else // Catch all for whats left.
{
$TwiMLResponse = “<Message>Sorry, Me No understand. Try Again.</Message>”;
}
}
else
{
$TwiMLResponse = “<Message>Sorry, Your not authorised for this.</Message>”;
}

header(“content-type: text/xml”);
?>

<Response><?php echo $TwiMLResponse; ?></Response>

This script will check that the inbound number is able make conference room pin numbers and if so will generate a 4 digit pin that will then be distributed back to the user.

Now when we text our number the body “Conference” or “Conf” from an authorised phone it will generate a pin number and respond back with details of the conference room in a SMS message:

 

Conf Details

Conference Room Details

 

You can then copy and paste this SMS message into a group SMS or Whatsapp and allow people to call into the conference room.

Now we have the SMS part setup we need to build a script that can welcome the caller, get the pin number and then route them to the correct conference based on that response.

<?php

// Check to see if a Conf Pin has been inputted. If so, make a Conf room with that pin.
$confPin = $_GET[“Digits”];

// If no conf Pin ask the caller to enter a Conf pin or else hangup.
if (isset($confPin)){
$TwiMLResponse = “<Say voice=\”alice\”>Placing You into Conference Now.</Say><Dial><Conference>”. $confPin .”</Conference></Dial>”;
}
else
{
$TwiMLResponse = “<Gather method=\”GET\” timeout=\”25\” numDigits=\”4\”><Say voice=\”alice\”>Hello and welcome to the conference line. Please enter the Conference Pin.</Say></Gather><Say>I’m Sorry I didnt catch that</Say>”;

}

header(“content-type: text/xml”);
?>

<Response><?php echo $TwiMLResponse; ?></Response>

 

Here in this script we are checking to see if the GET method has been passed with any digits, indicating that the caller has already been greeted and input a conference pin. If we have a conference pin then we can use the digits to put his caller into that conference room.

 

This is a very simple conference line setup tool, and it will need some further modifying to make it secure. For example right now any 4 digit numbers will create a conference room. You may wish to modify the code so that only generated pin numbers can be used and those numbers cannot be reused – entirely up to you.

 

So finally after many months of development, design, build, rebuild and writing of code. I have some data and information on my beehive! Its remarkable how much data you can get and learn about an environment by monitoring a few points over time. At the moment the BeeBetaBox is currently loading up, sending a HTTP  POST to an end point with lots of data about the beehive every 10 mins. This data is rolled into a database and then assembled together to generate graphs showing temperature over time Because I capture the GPS co-ordinates of the hive as well we can then use this to make a lookup against a weather service and provide the weather predictions for the next 3 days. Handy if your hive is remote and you want to see about a visit soon!

BeeSafe Graph

Following on my expansion into telephony posts (See a previous one, on making FreePBX work with Twilio). A lot of people have been asking me to provide more information on how to make your phone say things or play and MP3 file.  In particular while in a conference room…

Lets break this down into two parts; Making ‘Say or Play Bots’ and then adding our ‘Say or Play Bot’ to a conference and doing something.

Making a ‘Say or Play Bot’

Using Twilio there are lots of ways to make an automated voice say something to a caller / listener;

Twimlet Message (https://www.twilio.com/labs/twimlets/message) Static Message or MP3 file
TwimelBin (http://twimlbin.com) Static Message
Static XML hosted on your webserver Static Message
Dynamic web script that generates custom Say XML hosted on your webserver Dynamic Message
Dynamic web script that plays a custom message pending some criteria Dynamic Message

Twimlet Message:

In this example we are going to use a Twimlet message to say “Hi, This is you’re 9 AM Meeting Reminder, The current time is 8.55 AM. You have a meeting with Bob in 5 minutes.”

The message could be anything, in this case I’ve choose to use a meeting reminder message. If you follow the URL: https://www.twilio.com/labs/twimlets/message You can input your message into the Twimlet generator and it will spit out the URL you need to use with Twilio to get your message spoken:

http://twimlets.com/message?Message%5B0%5D=Hi%2C%20This%20is%20you’re%209%20AM%20Meeting%20Reminder%2C%20The%20current%20time%20is%208.55%20AM.%20You%20have%20a%20meeting%20with%20Bob%20in%205%20minutes.&

As you can see our message has now been encoded into a URL form, the spaces between words have been filled in with %20 if we were to buy a phone number now and use this in the Voice URL we would hear this message.

Twimelbin:

Twimelbin is an external tool that you can use to test writing your TwiML (XML) writing skills.  It will validate your TwiML and ensure that the syntax is correct, you can then use the URL link provided to reference this TwiML in your Twilio account.  In this example I’m going to copy and paste my TwiML here so you can see what the structure looks like:

<?xml version=”1.0″ encoding=”UTF-8″?>
<Response>
<Say>Hi Caller.</Say>
<Say>I’m just in the shower at the moment</Say>
<Say>Please let me wash my hair in peace and I will call you back later today</Say>
<Say>Thanks!</Say>
</Response>

Here you can see I have linked lots of ‘Say’ commands together in one response. We could if we wanted to be annoying (if!) get each command to be spoken in a different voice or even language (https://www.twilio.com/docs/api/twiml/say) but ill skip that for now.

When your finished composing your Twimelbin entry you take the URL at the top of the page and use this to look up your TwiML in your phone number URL.

Static XML hosted on your own machine:

Static XML and a Twimelbin response are exactly the same, the only difference that one is hosted on your platform and one is hosted by Twimelbin. There are benefits to both; I won’t go into the merits of self hosting vs a 3rd party for any kind of HTTP activity here.

Dynamically generated TwiML response: 

This is where is gets fun! With a dynamic script we can make our message be customised to the caller, the time of day, the weather or any other factor we want! Lets say for example that we have two callers; Mathew and Steve. Mathew’s number is +44123456 and Steve’s is: +44987654 as we are generating this response on demand we can input these names into the <Say> response and give the caller a more personal response.

In this example I’m using PHP, but you could easily use another web language.

<?php

$people = array(
“+44123456″=>”Mathew”,”+44987654″=>”Steve”);

// if the caller is known, then greet them by name
if(!$name = $people[$_REQUEST[‘From’]]) $name = “Caller”;

// now greet the caller
header(“content-type: text/xml”);
echo “<?xml version=\”1.0\” encoding=\”UTF-8\”?>\n”;
?>
<Response>
<Say>Hello <?php echo $name ?>.</Say>
</Response>

In this example, I made an array of data – mine and Steve’s number and then used the array to look up the name, if either Steve or I called the Twilio number from those numbers it would say Hi ‘Steve / Mathew’ if none of the numbers were recognised the caller would be just greater as just a ‘Hello Caller’

You can use the same kind of dynamic scripting language to play specific files, this could be to either specific times of the day, caller ID’s or special events.

I won’t go into the code here but the basic set up is:

IF event is true

Do this

Else (if not true)

Do this

So for example:

If time = before 12

Play the morning MP3 file

Else (If not true)

Play the Afternoon MP3 file

an example of this in PHP would be:

<?php

if (date(‘H’) < 12) {
$mp3_file=”http://domain.com/morning_mp3.mp3″;
}
else
{
$mp3_file =”http://domain.com/afternoon_mp3.mp3″;
}

// Play the AM / PM file to the caller
header(“content-type: text/xml”);
echo “<?xml version=\”1.0\” encoding=\”UTF-8\”?>\n”;
?>
<Response>
<Play><?php echo $mp3_file; ?></Play>
</Response>

When this script is called it will check the time, if the clock is before 12 it will fetch the morning MP3 file and if its in the afternoon  it will fetch the afternoon mp3 file. You could go one step further and make an evening file. But for this setup lets assume an morning and afternoon setup 🙂

So whats a bot?

In simple terms a bot is a program / application that just does one thing. In the use case here you could have a phone bot that people could ring and it would recite company open hours.

Example:

http://twimlets.com/message?Message%5B0%5D=Hello%20and%20welcome%20to%20Mathew’s%20super%20store.%20Our%20open%20hours%20are%208%20AM%20to%207%20PM%20Monday%20to%20Friday.%20&Message%5B1%5D=We%20are%20open%20Saturdays%2C%20from%2010%20AM%20to%203%20PM.%20We%20are%20not%20open%20Sundays&Message%5B2%5D=Have%20a%20nice%20day.&

 

This Twimlet just informs the callers of the times, Mathew’s superstore will be open.

 

In recent years, the need for physical internet security has grown, with websites being comprised constantly, we need a way to identify the real you from the internet you..

Enter the world of Two Factor Authentication. This pairs something you have, and something you know.. in our case, a mobile phone and a password.

Imagine signing into a website, after you put your username and password in the website sends you a SMS message or a quick voice call to actually make sure its you.

Using Twilio as the SMS / voice gateway this is possible and really easy to implement, particularly into a PHP server.

You will need:

  1. A Twilio Account – with Twilio Phone number
  2. A PHP webserver
  3. A copy of the TwoFactor Auth script found at: https://github.com/dotmat/TwilioTwoFactorAuth

If you haven’t already, please sign up for a trial account at Twilio : https://www.twilio.com/try-twilio

Once you have signed up you will need to edit the file: TwoFactorAuthProcessor.php placing your AccountSID, Auth Key and Twilio phone number in the top part of the file.

I have included in the git a quick index page that you can fill in, the page will make a HTTP POST to the processor and generate a two-factor passcode which it will either call or SMS to your phone.

Using Two-Factor authentication on your website will make your service more secure and provide peace of mind to your customers / users that even with a security breach, your users remain safe and malicious users are not able to gain access to your platform as they do not have the end users phone – something needed to pickup the two factor key.

 

So one of the buzzword’s used in 2012 was ‘Big Data’, representing the interconnection of lots of databases from a variety of sources all communicating together.

Why might you want to engage with big data? Well say your website or app wants to make use of a post code search tool to confirm someones address, or allow your visitors to look up a weather report for a holiday destination you are offering without the user leaving your website or app.

This is achieved through the use of some technology known as ‘web services’ or an ‘Application Programming Interface’ (API).

One of my projects for 2013 involves making use of API’s to load data from a web server so I thought I would share how API’s work through this demo:

Lets say you have a database of recipes containing:

  • Recipe ID
  • Title
  • Thumbnail of the Dish
  • Ingredients & Method
  • Author

Next you would need to define what formats you want your data to be presented back, in this case I am going to use JSON and XML formatting.

On your web server create a new folder or appropriate place to store your API data file. In my case I have chosen: domain.com/api_interface/ and add a new file titled ‘API.php’

Inside API.php we can start to add some code:

<?php

//Checking and Getting the two variables format and number of records
if(isset($_GET[‘format’]) and intval($_GET[‘num’])) {

//Set our variables
$format = strtolower($_GET[‘format’]);
$num = intval($_GET[‘num’]);

In this code we open the PHP tags and check that we are getting two variables from the HTTP request – the format (either XML or JSON) and num (number of rows of data).

After this we need to connect to the database and start to query for data:

//Connect to the Database
$con = mysql_connect(“localhost”,”username”,”password”) or die (‘MySQL Connection Error.’);
mysql_select_db(“database_name”, $con) or die(‘MySQL Table Error.’);

//Run the API query
$result = mysql_query(‘SELECT * FROM table ORDER BY `recipe_id` ASC LIMIT ‘ . $num, $con) or die(‘MySQL Query Error.’);

This query will look-up the table ‘table’ from the database ‘database_name’ and return in ASCENDING order rows of data.

Now we have the data we can build an array and begin to present the data we would like.

//Preapre our output
if($format == ‘json’) {

$recipes = array();
while($recipe = mysql_fetch_array($result, MYSQL_ASSOC)) {
$recipes[] = array(‘post’=>$recipe);
}

$output = json_encode(array(‘posts’ => $recipes));

Fortunately for us PHP includes an encoder for JSON so specifying that we want the data in JSON format we can load the data into an array and then write the data directly into the correct format.

If on the other hand we would like our data in XML format we can use a loop inside php to load the array and then fill in the XML tags to present back the XML format required:

elseif($format == ‘xml’) {

header(‘Content-type: text/xml’);
$output .= “<?xml version=\”1.0\”?>\n”;
$output .= “<recipes>\n”;

for ($i = 0 ; $i < mysql_num_rows($result) ; $i++)
{
$row = mysql_fetch_assoc($result);
$output .= “<recipe> \n”;
$output .= “<recipe_id>” . $row[‘recipe_id’] . “</recipe_id> \n”;
$output .= “<recipe_name>” . $row[‘title’] . “</recipe_name> \n”;
$output .= “<recipe_img_small>” . $row[‘thumbnail_photo_url’] . “</recipe_img_small> \n”;
$output .= “<recipe_link>http://www.domain.com/recipes/recipe_detail.php?=” . $row[‘recipe_id’] . “</recipe_link> \n”;
$output .= “</recipe> \n”;
}

$output .= “</recipes>”;

The else if statement is connected to the IF statement above and relates to the users choice of data they would like (JSON Vs XML). As the If statement is run it loops through the statement filling in the blanks with data from the Array creating a complete XML file.

This is what the files look like in their respective outputs.

JSON:

{“posts”:[{“post”:{“recipe_id”:”1″,”title”:”Quick and Easy Rice”,”large_photo_url”:”tbd”,”thumbnail_photo_url”:”tbd”,”ingredients”:”Rice\r\nBoiling Water\r\nSesame Oil – Optional\r\n”,”method”:”Cook some rice”,”Author”:”Mathew”,”thumbs”:”1″}}]}

XML:

<recipes>
<recipe>
<recipe_id>1</recipe_id>
<recipe_name>Quick and Easy Rice</recipe_name>
<recipe_img_small>tbd</recipe_img_small>
<recipe_link>http://www.domain.com/recipes/recipe_detail.php?=1</recipe_link>
</recipe>
</recipes>

Building an API like this gives developers the most amount of flexibility when it comes to interfacing with your information and data.

Its worth noting that this API has got NO limitations attached to it and that should someone get a hold of your the API they would be able to spam your web server countless times bringing it down. I HIGHLY recommend the use of an API Key system such as mashery.com or  3scale.net/