Since we began our XiVO adventure a couple months ago, the most requested feature has been direct support for Google Voice. For those in the United States, it remains the cheapest VoIP solution on the planet (when it works) with unlimited free calls throughout the U.S. and Canada. While we’ve had Google Voice functionality in XiVO through the Simonics SIP to Google Voice Gateway since the outset, there still were some who preferred to keep their credentials and tokens to themselves. And then there were those that found the $4.99 per line Simonics setup fee too rich for their blood.
To celebrate the new school year, today we’re pleased to provide a new tutorial and script that bolts Google Voice with OAuth authentication onto Incredible PBX for XiVO. Our extra special thanks goes to Sylvain Boily, the father of XiVO, for his selfless work in bringing this to fruition in less than a day. That tells you just how adaptable the XiVO platform really is. We’ve simply added a little window dressing to ease the pain for those just getting started with XiVO and Incredible PBX.
Overview. If you’re new to Google Voice, here’s how the installation scenario goes. First, you set up a Gmail account at gmail.com. Next, you create a Google Voice account. Then, you configure Google Voice for use with Asterisk®. Next, you obtain your Google Voice OAuth 2 Refresh Token which becomes your password to use in configuring Google Voice on the XiVO platform. Next, using SSH or Putty, you log into your XiVO server as root and download and run the installation script to get your Google Voice credentials set up in XiVO. Finally, you log into the XiVO GUI with a browser and set up a custom trunk as well as an outgoing and incoming route for Google Voice calls. To add more Google Voice trunks, you simply repeat the drill. You now should have a perfectly functioning, free VoIP platform compliments of Google and Sylvain Boily and his development team. Let’s get started.
Configuring Google Voice for Use with XiVO
Click on the Settings icon (upper right corner). Make certain that Forward Calls to Google Chat is checked. Uncheck your original forwarding number. Next, click on the Calls tab. Make sure your settings match these:
- Call Screening – OFF
- Call Presentation – OFF
- Caller ID (In) – Display Caller’s Number
- Caller ID (Out) – Don’t Change Anything
- Do Not Disturb – OFF
- Call Options (Enable Recording) – OFF
- Global Spam Filtering – ON
Under the Voicemail tab, plug in your email address so you get notified of new voicemails. Then click Save Settings. Down the road, receipt of a Google Voice voicemail will be a big hint that something has come unglued on your PBX.
UPDATE: Google has improved things… again. You may not see the options documented above at all. Instead, you may be presented with the new Google Voice interface which does not include the Google Chat option. But fear not. At least for now there’s still a way to get there. After you have set up your new phone number, click on (1) Settings -> Phone Numbers and then click (2) Transfer (as shown below). That returned the old UI. Make sure the Google Chat option is selected and disable forwarding calls to default phone number.
One final word of caution is in order regardless of your choice of providers: Do NOT use special characters in any provider passwords, or nothing will work!
Now it’s time to obtain your OAuth 2 credentials. Even though it’s a bit more work on the front end, the good news is you won’t have to worry about your Google Voice trunks failing when Google phases out plain-text passwords. The other good news is you won’t be passing your plain-text Google Voice credentials across the Internet for everyone in the world to see.
Obtaining Your Google Voice OAuth 2 Credentials for XiVO
While you’re still logged into your Google Voice account, you need to obtain a refresh_token which is what you’ll use instead of a password when setting up your Google Voice account with XiVO. Here’s how.
1. Be sure you are still logged into your Google Voice account. If not, log back in at https://www.google.com/voice.
2. Go to the Google OAUTH Playground using your browser while still logged into your Google Voice account.
3. Once logged in to Google OAUTH Playground, click on the Gear icon in upper right corner (as shown below).
3a. Check the box: Use your own OAuth credentials
3b. Enter Incredible PBX OAuth Client ID:
3c. Enter Incredible PBX OAuth Client secret:
3d. Click Close
4. Click Step 1: Select and Authorize APIs (as shown below)
4a. In OAUTH Scope field, enter:
4b. Click Authorize APIs (blue) button.
5. Click Step 2: Exchange authorization code for tokens
5a. Click Exchange authorization code for tokens (blue) button
5b. When the tokens have been generated, Step 2 will close.
6. Reopen Step 2 and copy your Refresh_Token. This is the “password” you will need to enter (together with your Gmail account name and 10-digit GV phone number) when you add your GV trunk in the Incredible PBX GUI. Store this refresh_token in a safe place. Google doesn’t permanently store it!
7. Authorization tokens NEVER expire! If you ever need to remove your authorization tokens, go here and delete Incredible PBX Google Voice OAUTH entry by clicking on it and choosing DELETE option.
Switch back to your Gmail account and click on the Phone icon at the bottom of the window to place one test call. Once you successfully place a call, you can log out of Google Voice and Gmail.
Yes, this is a convoluted process. Setting up a secure computing environment often is. Just follow the steps and don’t skip any. It’s easy once you get the hang of it. And you’ll sleep better.
Downloading and Installing Google Voice with OAuth 2 for XiVO
Now it’s time to reconfigure XiVO to use Google Voice with OAuth 2. Before you begin, write down your 10-digit Google Voice phone number, your Google account name without @gmail.com, and your Refresh Token from the previous step.
Log into your server as root using SSH or Putty. Then execute the following commands to kick off the install:
cd /root apt-get update wget http://incrediblepbx.com/gvoauth-xivo.tar.gz tar zxvf gvoauth-xivo.tar.gz rm -f gvoauth-xivo.tar.gz ./add-gvtrunk
Plug in your Google Voice phone number and credentials when prompted. Then check your work carefully. When the install finishes, fire up your favorite browser to finish the setup using the settings that were provided.
Configuring XiVO for Google Voice OAuth
From a browser pointed to the IP address of your server, log in to XiVO as root with your GUI password.
Choose Services.IPBX.Trunk Management.Customized. Click on + Add to create a new custom trunk. Configure the trunk using the settings provided by the installer and click the Save button. The Trunk Name will be your actual gmailname (without @gmail.com). Interface will be Motif/gmailname (using your actual Gmail name). Interface suffix will be @voice.google.com. And the Context will be Outcalls (to-extern).
Next, choose Services.IPBX.Call Management.Incoming Calls. Click on + Add to create a new inbound route for your Google Voice DID. This is where you tell XiVO how to route calls placed to your Google Voice number. For your DID, enter your 10-digit Google Voice number. For the Context, choose Incalls (from-extern). Then choose from the pick lists to select a Destination and Redirect option for the incoming calls. It could be an extension, a ring group, a conference room, or an IVR. Click Save when you’re finished.
Finally, choose Services.IPBX.Call Management.Outgoing Calls. Click on + Add to create a new outbound route. Under the General tab, configure the route as shown below using a Name of out_gmailname (using your actual Gmail name). The Context should be Outcalls (to-extern). The Preprocess subroutine should be subr-gv-outcall. And the desired Custom Trunk should be dragged left to the selected column:
Under the Exten tab, add the desired 10-digit Exten string and trim off any prefix using Stripnum. Then click the Save button.
For example, for a first trunk, you might choose NXXNXXXXXX as the Exten with a Stripnum of 0. This would tell XiVO to route all 10-digit calls to this Custom GV Trunk. For a second Google Voice trunk, you might choose 9NXXNXXXXXX with a Stripnum of 1. This would tell XiVO to route 11-digit calls with a 9 prefix to this Custom Trunk AND to strip off the first digit (9) before sending the 10-digit call to Google Voice.
Taking Google Voice for a Test Drive with XiVO
That completes the Google Voice setup. You now should be able to place a call using your Google Voice trunk by dialing any 10-digit number. And calls placed to your Google Voice number should ring at the inbound destination you chose above.
If you have additional Google Voice trunks, simply run /root/add-gvtrunk again and insert the new credentials.
Should you ever need to delete a Google Voice account from your server, just run /root/del-gvtrunk with the name of the Google Voice trunk to delete. Enjoy your free phone service!
— Ward Mundy (@NerdUno) April 22, 2016
Need help with Asterisk? Visit the PBX in a Flash Forum.
Special Thanks to Our Generous Sponsors
Awesome Vitelity Special. Vitelity has generously offered a terrific discount for Nerd Vittles readers. You now can get an almost half-price DID from our special Vitelity sign-up link. If you’re seeking the best flexibility in choosing an area code and phone number plus the lowest entry level pricing plus high quality calls, then Vitelity is the hands-down winner. Vitelity provides Tier A DID inbound service in over 3,000 rate centers throughout the US and Canada. When you use our special link to sign up, Nerd Vittles gets a few shekels down the road to support our open source development efforts while you get an incredible signup deal as well. The going rate for Vitelity’s DID service is $7.95 a month which includes up to 4,000 incoming minutes on two simultaneous channels with terminations priced at 1.45¢ per minute. Not any more! For our users, here’s a deal you can’t (and shouldn’t) refuse! Sign up now, and you can purchase a Tier A DID with unlimited incoming calls and four simultaneous channels for just $3.99 a month. To check availability of local numbers and tiers of service from Vitelity, click here. NOTE: You can only use the Nerd Vittles sign-up link to order your DIDs, or you won’t get the special pricing! Vitelity’s rate is just 1.44¢ per minute for outbound calls in the U.S. There is a $35 prepay when you sign up. This covers future usage. Any balance is refundable if you decide to discontinue service with Vitelity.
3CX is a software PBX that’s easy to install & manage. It includes integrated softphones, WebRTC conferencing and essential add-ons out of the box, at no additional cost. Try the free edition at www.3cx.com. Better yet, download the PIAF5 ISO powered by 3CX. Free version includes support for 8 simultaneous calls with a SIP trunk.
Some Recent Nerd Vittles Articles of Interest…