Loyal readers already know that voice recognition applications occupy a special place in the Incredible PBX® toolchest. Over 8 years ago, we introduced Wolfram Alpha integrating the world’s largest almanac into Asterisk®. And today we’re pleased to add Amazon’s Alexa to the Incredible PBX fold for our latest Incredible PBX 2021 for Debian, Raspberry Pi and CentOS 7 builds. Just dial 5555 and tell Alexa what you’d like to know or do. If you’ve been sleeping under a rock these past few years, Alexa provides not only a thesaurus but also current news and weather, cooking tips and recipes, calendars, movie showtimes and data, Amazon purchasing, shopping lists, reminders, maps, music.everything, home automation control to turn on your lights, lock your doors and adjust your thermostat, sports scores and scheduling, grocery shopping, and almost anything else you can imagine asking for. And our special tip of the hat goes to Russell Grokett for his creativity in bringing the Alexa platform to the Asterisk community. Here’s a simple graphic showing the call flow in a typical Alexa call from any SIP phone connected to Incredible PBX:

Before we get started, let me offer a few words of caution. You’ll need to be a careful reader and follow the instructions below carefully to get Alexa working. Amazon uses OAuth 2 authentication which is secure (and tedious) by design. The good news is you only have to go through this setup exercise once after which Alexa will be available at any time without further tweaking. We’ve made some changes in Russell Grokett’s original design to hopefully simplify the OAuth procedure and to adjust some of the configuration to correctly interface with newer releases of the open source components including sox which handles the audio translations between Asterisk and Alexa. All of the code is licensed pursuant to GNU GPLv3.

Prerequisites. Before you begin, you’ll need a working Incredible PBX 2020 platform running CentOS 7, or Incredible PBX 2021 running Debian 10, or the latest Incredible PBX release for Raspbian preferably running on a Raspberry Pi 4 with at least 2GB of RAM.

Overview. There are four steps in today’s installation procedure. First, we will download and install a number of open source components on Incredible PBX by running a simple script. Second, you’ll need to sign up for both an Amazon account if you don’t already have one AND an Amazon Developer Account. Third, we’ll create an Alexa Voice Service application and set up the Alexa Security Profile for the application. Finally, using the credentials obtained during this setup process, we’ll configure the components on your PBX to talk to Alexa. Be advised that the Amazon license we will be using authorizes only private, non-commercial use. Today’s design does not meet Amazon’s terms for commercial and/or public use!

1. Installing Alexa Basics for Incredible PBX

Log into your server as root and issue the following commands to download and install the basic components to support Alexa integration into Incredible PBX:

cd /
wget http://incrediblepbx.com/incredible-alexa.tar.gz
tar zxvf incredible-alexa.tar.gz
rm -f incredible-alexa.tar.gz

2. Creating an Amazon and Amazon Developer Account

If you don’t already have one, you can create an Amazon account at amazon.com. Write down your email address and password. You’ll need them in the following steps. Next, navigate to the Amazon Developer Portal and set up a free account using your Amazon credentials.

3. Creating Voice Service Application & Security Profile

After creating your Amazon developer account, we’re ready to create a product and security profile. Begin by logging into the AVS Dashboard. Click GET STARTED to begin.

Click PRODUCTS. Then click ADD NEW PRODUCT. Fill in form as shown below. Click NEXT.

  • Product Name: IncrediblePBX
  • Product ID: IncrediblePBX
  • Product Type: Application with Alexa built-in
  • Product Category: Communications
  • Brief Product Description: Alexa for Incredible PBX
  • User Interaction: Hands-free
  • Distribute Commercially: NO
  • Children’s Product: NO

In LWA Security Profile dialog, click CREATE NEW PROFILE. Fill in template. Then NEXT.

  • Security Profile Name: IncrediblePBX
  • Security Profile Description: Incredible PBX security profile

In the second LWA Security Profile dialog, copy your Security Profile ID, Client ID, and Client Secret to a text file so that you can use them in the following steps.

In the Allowed return URLs field, create two entries clicking ADD button after entering each:

  • http://localhost
  • https://actual-Incredible-PBX-IP-address:5000/code

Check the I Agree checkbox and then click FINISH.

Your Product should now appear as successfully configured in Alexa Voice Service overview.

Next, navigate to: https://developer.amazon.com/lwa/sp/overview.html.

Click Select a Security Profile and choose your IncrediblePBX profile. Click CONFIRM.

In the Consent Screen dialog, enter the following and then click SAVE.

  • Consent Privacy Notice URL: http://dummyurl.com
  • Consent Logo Image: leave blank

Verify your ClientID and Secret that you wrote down above.

Cut-and-paste the following as a single line of code into your favorite text editor. Or you can simply edit /root/Alexa-URL which contains the same code.

Replace YOURCLIENTID in the above code substituting your actual Alexa Client ID.

Next, select the entire block of code that now includes your actual Client ID and paste it into the Address URL of your favorite browser. You should be prompted for your Amazon user credentials. Once you sign in, click ALLOW. You then should see an Unable to Connect error message. This is fine. What we actually need is the Token which now is shown immediately after code= in the Address URL of your browser. Copy everything after code= up to the &.


With YOURTOKEN, Client ID, and Client Secret in hand, proceed to the next section.

4. Activating Alexa in Incredible PBX

Log into Incredible PBX as root and navigate to the /root directory. Make a copy of grant-token.sh in case you make a mistake. Now edit grant_token.sh. Replace YOURTOKEN with your actual Token. Replace YOURCLIENTID with your actual Alexa Client ID. Replace YOURCLIENTSECRET with your actual Alexa Client Secret. Save the file and then run the script: ./grant_token.sh.

The script will return a JSON message that includes both an access_token and a refresh_token. It will be a very long single string that you should cut-and-paste and save for a rainy day. The string can be parsed in an editor so that it looks something like this:

Access tokens expire every hour, but this refresh token never expires. We’ll use the refresh token to generate a new access token whenever Alexa is run from an Asterisk extension. So cut-and-paste the very long refresh_token and save it with your Client ID and Client Secret.

Next, change to the /var/lib/asterisk/agi-bin directory and make a copy of token.pl in case you make a mistake. Then edit token.pl and scroll to the my $post line (line 16). Replace YOUR_REFRESH_TOKEN with the refresh_token from above. Replace YOUR_CLIENT_ID with your actual Client ID. And replace YOUR_CLIENT_SECRET with your Client Secret.
Save the file.

TIP: If you decide to install Alexa on more than one of your PBXs, the setup process only takes a couple minutes. Complete Step #1 as documented above. Then copy the my $post line from token.pl that includes your credentials and replace the my $post line of token.pl script in your second PBX. Done.

Now you’re ready to try things out. From the command line, issue the command: ./token.pl

List the results like this: cat /tmp/token.resp

There should be no errors and the results should look something like this:

IMPORTANT: Don’t forget this step or future queries from Asterisk will fail since our test generated files with root permissions only: rm -f /tmp/token*

Now we’re all set to use Alexa from your PBX. From an extension on your PBX, dial 5555. When prompted, say "What’s the weather for today?" After receiving the response from Alexa, you can either hang up or say another query.

We’ve documented some Alexa queries and skills in this thread on the VoIP-Info.org Forum.

If you have problems getting all the pieces to work, check over the steps again. You may also wish to consult the original documentation. Ignore references to differing file locations.

Republished: Tuesday, August 3, 2021

Need help with Asterisk? Visit the VoIP-info Forum.



This article has 1 comment

  1. Using your phone with its limited input, output options to control stuff or provide information is a really cool idea.

Leave a comment

Your email address will not be published. Required fields are marked *