Increase conversions with Voice Dialing Geographic Permissions REST API

Time to read: 3 minutes

April 01, 2019
Written by
Tim Beyers
Twilion

qCEEQApMAmTzQqLYqECoaOnFsb8pyqkJtNYuGLj6sjUAGQ-uGx6k6sGO3LdCqTXusg_uhzWK1KrX23_d5gjFCdRFxy4gVIr-R3od4RMZadpY2jmkGCqiNpomhi2BBDVXQssEdsAr

Looking to improve your international conversions? Trust us, we’ve grappled with this too, so we want to give you all the tools so your new trial users have a delightful first experience with your product.

That’s why when a new user signs up for a free trial account on Twilio we detect the user’s country and automatically enable dialing permissions for them.  We let the Twilio trial user enable calling to all of the 218 countries and territories but to protect Twilio from toll fraud they can only enable calling to low-risk destinations and during the trial experience they must call a verified caller ID.

We want our partners that build and re-sell Twilio powered solutions to give their customers the same low-friction experience so that’s why we’re excited today to announce the General Availability of the REST API for Voice Dialing Geographic Permissions.

Let’s see this new API in action.

How to configure permissions for new signups

Let’s suppose you have a new trial user located in Brazil that you detected the Geolocation of the user’s IP address using maxmind.  After you create a new subaccount using the REST API for your tenant, you want to give this user permissions to make outbound calls to Brazil phone numbers.  

curl -X POST https://voice.twilio.com/v1/DialingPermissions/BulkCountryUpdates \
-F 'UpdateRequest=[ {  \
"iso_code"                            : "BR",  \
"low_risk_numbers_enabled"            : "true",  \
"high_risk_special_numbers_enabled"   : "false", "high_risk_tollfraud_numbers_enabled" : "false"  \
} ]'\
-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token

Replace ACXXX... above with your subaccount Account SID and your_auth_token with your private auth token

By default, new subaccounts will inherit the Master Project permissions.  So now you must disable inheritance.

curl -X POST https://voice.twilio.com/v1/Settings \
--data-urlencode "DialingPermissionsInheritance=False" \
-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token

That’s it!

You can use the REST API for all your Projects and subaccounts.

Pricing

Voice Dialing Geographic Permissions are available to all customers for free.

Business Insight

How do I know if my new trial users need updated permissions? You can navigate to the Console debugger or use the REST API and search for the warnings 21215, 32205,13227 which correspond to calls blocked by Geo Permissions due to Programmable Voice or Elastic SIP Trunking.  These blocked calls could indicate a lost revenue opportunity or could signal that a fraudster is planning an attack. Make sure you select the subaccount you are interested in first.

So far, I’ve told you how to improve your customer’s onboarding experience. But I haven’t told you how you can change permissions on your existing subaccounts to reduce your toll fraud risk. Before I show you that, let’s review what we mean by risk.

Destinations classified by risk

In each country, there are low-risk and high-risk group of destinations. The high-risk destinations are groups of prefixes classified as either (1) Special Services number ranges or (2) High-risk for toll fraud number ranges.

  1. Special Services number ranges include premium, shared-cost, and special services number types.  These number ranges change infrequently and can be viewed in the Console or retrieved via REST API.
  2. High-risk for toll fraud number ranges include narrow ranges from 3rd party anti-fraud databases classified as high risk after Twilio analyzes millions of calls on the Twilio Super Network. Since number ranges used for toll fraud are regularly created Twilio updates the list multiple times per month. These ranges are not disclosed to further protect your account.

Best Practice

In most cases, businesses never need to call these high-risk destinations and you should disable calling them in the Console or with this REST API.

Reduce your risk

For this, you need a script that will disable high-risk destinations in each country Twilio supports calling to. You can extend the script to iterate through all your subaccounts if you like.

Prerequisite: Twilio Python Helper Library

from twilio.rest import Client
import json

# Your Account Sid and Auth Token from twilio.com/console
# DANGER! This is insecure. See http://twil.io/secure
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_token'

client = Client(account_sid, auth_token)

countries = client.voice.dialing_permissions.countries.list()

update_countries = []
for country in countries:
    update_country = {}
    update_country["high_risk_special_numbers_enabled"] = False
    update_country["high_risk_tollfraud_numbers_enabled"] = False
    update_country["low_risk_numbers_enabled"] = country.low_risk_numbers_enabled
    update_country["iso_code"] = country.iso_code
    update_countries.append(update_country)


bulk_country_update = client.voice \
    .dialing_permissions \
    .bulk_country_updates \
    .create(
         update_request=json.dumps(update_countries))
print(bulk_country_update.update_count)

When it comes to toll fraud there is no silver bullet. Voice Dialing Geographic Permissions is one pillar in your defence but you need to also consider rate limiting and identity verification. To learn more watch this talk or read our guide to toll fraud.

Learn more about the REST API here, and the Console experience here.

We can’t wait to see what you build!

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.