Connecting a Grandstream HT80X (HT801 or HT802) to Twilio SIP

March 7, 2021

The Inspiration

I'm diving into all of Twilio's products and trying to learn as much as I can about them. The best way I learn is by actually doing it and trying to build it myself. My focus on this project was learning about SIP Trunking. It seemed pretty straightforward, but as always the devil is in the details and there are always nuances to learn about everything.

Future Goal

I wanted to get an Analog Telephone Adapter, so I can hook up up an old landline telephone with an obnoxious bell and have it wake me up like an alarm clock ⏰.

Picking The Hardware

There's a bunch of Analog Telephone Adatpers (ATA) out there. I was also looking at the Cisco ATA 191 but ultimately settled on the Grandstream HT801 because it was less than $20 from someone on eBay and I found these instructions from Nick Busey on how to set up the device specifically with Twilio SIP. I thought that because it was a recent post, that I wouldn't have much difficulty trying to configure it. Here's the Amazon link.

Getting Started

I had orginally followed Nick's instructions but there were some drawbacks. I had trouble with inbound calls and also triggering calls with the REST API.

Twilio SIP ht801


  1. Open ports in your router's firewall
  2. Configure Outbound Calls
  3. Configure Inbound Calls
  4. Configure the Grandstream device

Unfortunately, in Nick's use-case, he only needed outbound calling, which made the phone only half as useful for me haha. I recognized his name as the creator/maintainer of the HomeLabOS project. So I knew I could find him on the HomeLabOS Zulip Chat and asked him a few questions on if he was able to get outbound AND inbound calling working. He graciously answered a few of my questions. Unfortunately, he doesn't use the device anymore and didn't look into getting inbound calls more.

So, at this point I was able to configure the device and have outbound calling going, but I needed more. So, I logged a Service Ticket with Twilio. Again, this was a good excuse to learn more about Twilio by using the products like Customer Support.

A customer service rep was able to help me troubleshoot the issue and taught me a few things along the way, like this... ~~

Pro Tip:

You can download the PCAP file and explore it with WireShark to explore the headers and see what's going on during the connection process.

Twilio SIP Console PCAP Download

During the connection process for incoming calls, he explained that the Contact section in the Header was trying to return the local IP address of the ATA box instead of my public IP address of my home internet connection -- so something was literally getting lost in translation, well the Network Address Translation (NAT).

Twilio SIP Support Screen Shot

At first, I ended up hard-coding my public IP address in this section of the Grandstream configuration like this:

Use NAT IP: 123.456.78.90

However, there were some issues if you put in your Public IP address -- better hope it doesn't change! This "hack" overrides the internal IP address that was being returned in the Header and allows incoming calls to come in. I tried to use a Dynamic DNS address but the field only allowed enough digits for an IP address.

With the first configuration, I was having trouble receiving calls via a REST API command. Investigating into the PCAP file helped me troubleshoot. After taking a step back, I ended up figuring the right configuration!

Create a SIP Trunk

Name it something and add an Origination URL:

Configure a SIP Domain in Twilio Programmable Voice

make the SIP URI something easy for you to remember. This will be the url of the Primary SIP Server on your Grandstream box. With that, you'll have to add a value to the IP Access Control List and a Credential List. The username/password you put in your Credential List will be the SIP User ID and the Authenticate ID on your Grandstream box.

twilio wake up call - SIP domain configuration

Create a Credential

Twilio Wake Up Call - Create a Credential

Configure Outgoing Calls with a TwiML Bin

While you're here, scroll down and add a TwiML Bin for when A Call Comes In so you can make outgoing calls.

<?xml version="1.0" encoding="UTF-8"?>
  <Dial callerId="+14151234567">{{#e164}}{{To}}{{/e164}}</Dial>

Twilio Wake Up Call - Outgoing Call Configuration

SIP Registration

Twilio Wake Up Call - SIP Registration

Screenshot of Grandstream Configuration

When I was looking for help on the configuration, I kept seeing sections but wanted the FULL image. So, here's mine, in its entirety.

Update the following fields:

  • Primary SIP Server:
  • SIP User ID
  • Authenticate ID
  • Authenticate Password
  • SIP REGISTER Contact Uses: WAN Address
  • Check SIP User ID for incoming INVITE
  • Dial Plan Prefix: +

Grandstream Device Configuration Updated

Confirm SIP Registration

You'll see your username and "Registered" on the Port Status line.

Twilio Wake Up Call - Confirm Registration

Configure Incoming Calls With a TwiML Bin

As outlined here

<?xml version="1.0" encoding="UTF-8"?>
  <Dial answerOnBridge="true">

Go to your phone number in the Numbers Tab and click on it. When a Comes In: run the TwiML Bin you just created above.

Next Steps

It'd be fun to setup a PBX server and have IP Phones with different extensions for each room in my house, but it's probably extreme overkill for what I need. Here's how I incorporate the ATA landline into a new type of Wake Up Call Alarm project.