How to set up an Obihai ATA to use Twilio

N.B.: This post has been superseded by a simpler set of instructions in a more recent post.

But, you say, Obihai analog terminal adapters like the OBi200, OBi202, and OBi212 already support Twilio natively. Why would I need these instructions?

The answer is that the native setup method utilizes the Twilio SIP Domains feature within Programmable Voice. This allows the OBi to register with Twilio, which is perfect for terminating calls into the OBi. However, when the OBi wants to originate a call, Twilio wants to send that call to a REST endpoint for handling. It also uses a format that is not compatible with Twimlets. So, if we use this method, we are in a position where we must provide an always-on REST endpoint for Twilio to hit every time the OBi endpoint would want to originate a call. This seemed like an undesirable dependency, especially since it would be in the path of potential emergency calls.

So, here is how to configure an OBi ATA and Twilio such that the SIP Domain is used for incoming calls, but an Elastic SIP Trunk is used for outgoing calls.

Incoming Calls

We will mostly stick to the normal Obihai method for this.

1. Create a new Programmable SIP Domain in the Programmable SIP dashboard:
   • The domain you enter in the “SIP URI” field is the domain you will use to configure OBiTALK.
   • In the “Voice Authentication” section, make a new credential list. Create a new username and password for your ATA; save these somewhere for now.
   • Enable the “SIP Registration” section. In the “SIP Registration Authentication” subsection, select the same credential list you created in the previous bullet point.
2. Register your ATA in the OBiTALK dashboard. (Most of this process is left as an exercise for the reader.)
3. On the OBiTALK configuration page for your ATA, click the Settings cog next to SP1 (or your first free SP), then click Next.
4. Click Twilio.
5. Configure the Twilio SIP Domain service:
   • Check all the boxes.
   • In “Your Domain,” enter the setting you used for “SIP URI” in the Twilio SIP Domain setup. Don’t enter the FQDN, just enter it as a single domain name (like “abc123”).
   • Enter the username and password that you put into the Twilio Credential List.
   • Click Submit.
6. Make a new TwiML Bin; probably call it the same thing as the username you used in the Credential List.
   • Put this in the Bin:
     <?xml version="1.0" encoding="UTF-8"?>
<Response><Dial answerOnBridge="true"><Sip>sip:mycreduser@mysipdomain.sip.us1.twilio.com</Sip></Dial></Response>
     Replace “mycreduser” with the username you used in the Credential list. Replace “mysipdomain” with the name of the SIP Domain you configured. Note the “us1” – you do have to incldue the region here.
   • Copy the Bin URL to your clipboard.
7. Edit the Twilio phone number that you want to connect to your ATA.
   • Find the “A Call Comes In” Webhook box, and paste the link to the TwiML Bin into that box.

At this point, incoming calls to your OBi should be working.

Outgoing Calls

1. Create a new Elastic SIP Trunk. We only care about the “Termination” page:
   • The domain you enter in the “Termination SIP URI” can be the same as the one from the Programmable SIP Domain. Or not, it doesn’t matter. In any case, the suffix is different (“.pstn.twilio.com”).
   • In the “Credential Lists” box, select the same credentials that you created for the Programmable SIP Domain.
2. On OBiTalk, click “OBi Dashboard,” then click your device.
3. Near the bottom of the page, click “OBi Expert Configuration,” then click “Enter OBi Expert.”
4. In the “Service Providers” section, browse around in the “ITSP Profile X General” section until you find one that is unused (no name configured).
5. Override the following settings:
   (To override a setting, uncheck both of its boxes, then input the setting.)
   • Name: TwilioTrunk
   • DigitMap: (<+>1xxxxxxxxxx|<+1>[2-9]xxxxxxxxx|<011:+>xx.|xx.|(Mipd)|[^*#]@@.)
     • What is going on here? This makes sure the numbers are in E.164 format. Twilio requires this. (I have not tested this extensively outside of the NANP.)
6. Submit those changes, then, for the same SP, head to “ITSP Profile X SIP.” Override the following settings:
   • ProxyServer: Your full Elastic SIP Trunk domain (example.pstn.twilio.com)
   • OutboundProxy: Your full Elastic SIP Trunk domain (example.pstn.twilio.com)
   • OutboundProxyPort: 5060
7. Submit these changes, then under the “Voice Services” section, find the first unused SP. Override the following settings:
   • X_ServProvProfile: Your TwilioTrunk SP
   • X_RingProfile: Your Programmable SIP Domain SP
   • X_CodecProfile: Your Programmable SIP Domain SP
   • X_RegisterEnable: Unchecked
   • AuthUserName: The username from the Credential List
   • AuthPassword: The password from the Credential List
   • URI: The E.164 number you wish to use as the Caller ID for this ATA’s outgoing calls. Example: +12125551212
8. Submit these changes, then under the “Physical Interfaces” section, select the relevant ATA port. Override these settings:
   • PrimaryLine: The SP you just configured
9. Submit these changes.

After the ATA restarts roughly 5000 times, outgoing calls should now work. Enjoy!

Other helpful resources

• Obihai’s guide to digit maps