Technical

Audio files can be retrieved from the Allison On Demand API using a simple REST style API. The API takes the following parameters

  • KEY
  • NAME

KEY
This is the access key assigned to you by Acumantra

NAME
The name you wish to search for

Requesting Audio

To request an audio clip for “George”, make an HTTP GET request for the URI http://api.allisonondemand.com/api/name/yourKey/george
Character casing does not matter for the the name.

INVALID OR EXPIRED KEY
If you provide an invalid, or expired API key, you will receive an HTTP 402 (Payment Required) status code.

REQUEST FOR A PRE-EXISTING AUDIO CLIP
The body of the HTTP response will be the audio clip in the requested format.
HTTP Response Headers
X-TextToSpeech: false

REQUEST FOR A NON-EXISTING AUDIO CLIP
The server will log your request, and it will be considered for recording by our voice artist. Using a text-to-speech engine, the server will send back a synthesized audio clip. To distinguish the computer generated audio from those recorded by the voice artist, the response will include X-Autogenerated: true in the headers.

HTTP Response Headers
X-TextToSpeech: true

SAMPLE CODE
The following Perl script connects the Allison On Demand web service to Asterisk via the Asterisk Gateway Interface (AGI). To use this script, copy it to /var/lib/asterisk/agi-bin and call it from your extensions.conf. This example AGI script downloads and plays a name from the allisonondemand.com and stores the file in the temp directory.

#!/usr/bin/perl -w

# Allison On Demand example script.
#
# This script is an example agi script that will
# download and play a name from the allisonondemand.com
# names database.  To use this script, copy it to
# /var/lib/asterisk/agi-bin and call it from your
# extensions.conf:
#
# agi(allisonOnDemand.agi, "John Doe", "wav")
#
# This script leaves the names in the temp directory
# so it probably should check there first before
# attempting to download the name again.
#
# For help with Allison On Demand please contact
# support@allisonondemand.com
#

use strict;
use LWP::UserAgent 5.66;

my %AGI;
my $temp  = '/tmp';
my $url   = 'https://api.allisonondemand.com/api/name';
my $token = 'your_api_key_goes_here';
my $agent = LWP::UserAgent->new;
$agent->timeout( 5 );

# Disable output buffering
$|=1;

# Read in the agi environment
while( <STDIN> ){
	chomp;
	last unless length( $_ );
	if( /^agi_(.+)\:\s+(.*)$/ ){
		$AGI{$1} = $2;
	}
}

# get the args
my $format = $AGI{'arg_2'};
my @names = split( ' ', $AGI{'arg_1'} );

# answer the call already
print "ANSWER \n";
my $result = <STDIN>;

# Loop through the names we got
foreach my $name ( @names ){

	my $response = $agent->get( "$url/$token/$name.$format", ':content_file' => "$temp/$name.$format" );

	if ($response->is_success && -f "$temp/$name.$format" ){
		print "STREAM FILE \"$temp/$name\" \"\" \n";
	        my $result = <STDIN>;
	} else {
		print "VERBOSE \"Failed to fetch $url/$token/$name.$format\" \n";
		my $result = <STDIN>;
	}

}

exit 0;

Listen To Samples

Download the sample audio to hear the difference.