The following quick start guide is written in PHP. Of course modify to suit your needs!
In this demo, when you dial your BlueVia Voice Number:
This demo will require you to have access to a web server, running PHP.
There are three files for the demo which you can find in the Quick Start demo code from github @todo: ADD LINK
Update the configuration of the BlueVia Voice Number to point to the location where you host PincodeConference.php. This is the starting location for this demo. After you have configured your BlueVia Voice Number and you dial it, BlueVia will make a HTTP POST request to the URL pointing to PincodeConference.php.The HTTP POST will contain notification information in the body of the request. Detail of the BlueVia Voice Call Notifications at this stage is not important, other than we are expecting to receive a CalledNumber notification type. In fact in this case it is the only notification we will retrieve.
So in the following case the first thing you do is get the notification detail from the HTTP POST Request from BlueVia. So in PincodeConference.php:
<?php
// Get the POST request body
if (($stream = fopen('php://input', "r")) !== FALSE){
$bodyContent = stream_get_contents($stream);
}
// get event data from the POST request body
$obj = json_decode($bodyContent);
$eventName = $obj->{'eventName'};
Then based on the notification type - again in this example the notification type will always be CalledNumber (A full list of notification types can be found in the BlueVia Voice Call Notifications section, you respond with a getDigits command.
// only provide a response if this is an CalledNumber event
if ($eventName == "CalledNumber") {
$response = "{
\"commands\": [
{
\"getDigits\": {
\"timeout\": 5,
\"numberOfDigits\": 1,
\"retries\": 2,
\"actionUrl\": \"<your-hostname-and-path>/eventHandler.php\",
\"speak\": {
\"text\": \"Press 1 to create a new conference. Press 2 to join an existing conference call.\",
\"voice\": \"Female\"
}
}
},
{
\"speak\": {
\"text\": \"Sorry, you didn't enter a selection in time. Please call and try again.\",
\"voice\": \"Female\"
}
},
{
\"hangup\":{
}
}
]
}";
echo ($response);
}
?>
In this case the getDigits command:
Looking at the eventHandler.php code. Again you retrieve the eventName from the HTTP POST request body, and in this case there is a switch based on the eventName, which in the case of request generate by BlueVia for a getDigits command will be a DigitsCollected notification. So the first case covered is the event that the called has selected 1, i.e. is a moderator on the conference
switch ($eventName) {
case "DigitsCollected":
$digitsCollected = $obj->{'digits'};
switch ($digitsCollected) {
case "1":
$response = "{
\"commands\": [
{
\"getDigits\": {
\"speak\": {
\"text\": \"Please enter the pin you wish to use for your conference, followed by the hash key\",
\"voice\": \"Female\"
},
\"finishOnKey\": \"#\",
\"timeout\": \"15\",
\"retries\": \"2\",
\"actionUrl\": \"<your-hostname-and-path>/startConference.php?state=moderator\"
}
},
{
\"speak\": {
\"text\": \"Sorry, you didn't enter the number in time. We can't help you\",
\"voice\": \"Female\"
}
} ]
}";
echo ($response);
break;
In this case we ask the ‘moderator’ for further input - to key in the pincode they wish to assign for the conference. The only significant difference in the getDigits command is:
Similarly, in the event that the getDigits response from PincodeConference.php is ‘2’, i.e a conference participant, the only change that is made is that the startConfernece.php is called specifying the response is from a conference participant
$response = "{
\"commands\": [
{
\"getDigits\": {
\"speak\": {
\"text\": \"Please enter the pin you wish to use for your conference, followed by the hash key\",
\"voice\": \"Female\"
},
\"finishOnKey\": \"#\",
\"timeout\": \"15\",
\"retries\": \"2\",
\"actionUrl\": \"<your-hostname-and-path>/startConference.php?state=participant\"
}
},
{
\"speak\": {
\"text\": \"Sorry, you didn't enter the number in time. We can't help you\",
\"voice\": \"Female\"
}
} ]
}";
echo ($response);
Finally in eventHandler.php you validate that the caller has entered a correct value. You can limit the input options that are actually available to callers - see the getDigits documentation, however in this case we are allowing any single digit to be entered. As a result if the keypad numebr pressed is not 1, or 2:
$response = "{
\"commands\": [
{
\"speak\": {
\"text\": \"Sorry you entered an incorrect value. Please try again\",
\"voice\": \"Female\"
}
},
{
\"redirect\": {
\"callbackUrl\": \"<your-hostname-and-path>PincodeConference.php\"
}
}
]
}";
echo ($response);
In this case we specify, via a speak command, that the user has entered an invalid value and then use the redirect command to return the user to the start of the call flow, so they can try again.
Finally based on the caller input you can add them to a conference based on the pincode they have entered. Looking at the final file in Quick Start Guide demo code - startConfernece.php
switch ($eventName) {
case "DigitsCollected":
$digitsCollected = $obj->{'digits'};
// if there is a hash in the $digitsCollected then strip it
$digitsLessHash = str_replace("#", "", $digitsCollected);
// switch based on state = moderator/participant
switch ($state) {
case "moderator":
$response = "{
\"commands\": [
{
\"dial\": {
\"conferenceName\": \"" . $digitsLessHash . "\",
\"conferenceProperties\": {
\"startOnEnter\":true
}
}
}
]
}";
echo ($response);
break;
case "participant";
$response = "{
\"commands\": [
{
\"dial\": {
\"conferenceName\": \"" . $digitsLessHash . "\",
\"conferenceProperties\": {
\"startOnEnter\":false
}
}
}
]
}";
echo ($response);
break;
In this case:
That’s it. With a few lines of code you have created a dial in conference service on your BlueVia Voice Number that supports multiple conferences, based on a pin-code access. This demo will allow you to have multiple conferences hosted from the same BlueVia voice Number.