International Voice Dialing Geographic Permissions, also known as Geographic permissions or Geo Permissions, exist to help you protect your application from fraud and abuse, or simply avoid unexpectedly high costs for voice or messaging usage.
For Voice, Geo Permissions control which countries and subsets of phone numbers you can dial out to from your Twilio project.
For further details, please see our documentation for how to Protect your Account with Voice Dialing Geographic Permissions.
How do International Voice Dialing Permissions work?
Twilio has segmented phone numbers for each of the countries we can reach into two buckets - one group of numbers with low fraud risk and another group that has higher risk. All Twilio accounts have access to the low risk number ranges right out of the box. You only need to enable calls to the country in the Console Voice Geographic Permissions page. High risk number ranges are enabled in the same way, but require upgraded accounts to access.
How can I tell if my calls are being blocked by Geo Permissions?
Outbound calls that are blocked by Geo Permissions will be flagged by one of the following notifications depending on the call type:
- 13227: Programmable Voice <Dial> Calls
- 21215: Programmable Voice API Calls
- 32205: Elastic SIP Trunking Calls
You may also encounter calls which are blocked by Twilio's blacklist which is separate from the geo permissions. These numbers are often blocked because of a high-risk of fraud or due to regulatory reasons. Calls blocked by the Twilio blacklist cannot be enabled with geo permissions and will be presented with one of the following error codes:
- 13225: Programmable Voice <Dial> Calls
- 21216: Programmable Voice API Calls
- 32203: Elastic SIP Trunking Calls
Blacklisted numbers failing with one of the error codes above can only be fixed by the Twilio Support Team. If you have a legitimate need to call a blacklisted number, please reach out to our Support team with an explanation of your use case.
Lastly, we recommend you monitor the Console Debugger or configure Alert Triggers for these errors to stay on top of your project's calling needs.
How to configure a Voice Geo Permission
Access your console and make sure you have Voice in your menu . If it is not there, please go to explore product and Pin it to your menu.
Once you already have in in your menu please access Voice > Settings > Geo Permissions:
On the Geo Permissions page, you will find two tabs - one for Low Risk and another for High Risk. Each tab will contain the list of countries that you can be enabled or disabled.
Please search for the country you want call to and make sure it is marked (checked) . If you encounter an issue calling a specific number, first make sure the Low Risk numbers are enabled for that country. If the issue persists, then try each High Risk category one at a time.
Geo Permissions and Subaccounts
In all Twilio subaccounts, you can setup new numbers, new apps, new trunks, and more, and all of it will work apart from what you already have on your master account. While subaccounts have their own usage and resources, they do not have their own account balance and instead share it with their parent account.
A subaccount is an ideal way to separate your phone numbers, usage, and application settings for a specific end customer. Subaccounts are especially useful for Twilio's CRM reseller customers who have their own unique users / customers and must keep each of their data and usage separated.
But what about geo permissions? Well by default, Twilio subaccounts inherit all permissions from the parent account. However, this behavior can be disabled so the subaccount can have different permissions from the parent account.
To disable Voice Geographic Permission inheritance for a given subaccount, login to the subaccount then follow the same path shown above for a parent account to access the Geo Permission settings for the subaccount: Voice --> Settings --> Geo Permissions.
You will see a toggle to "INHERIT FROM MASTER". Simply click the toggle to disable it. When you click the toggle, there will be a warning, and you will need to click "YES" to proceed. After that, you will see the different tabs and the country list to make the required configuration for that subaccount separate from the parent account.
Can I change Voice Geographic Permissions programmatically with the API?
Yes! In addition to the Console, the Voice Geographic Permissions can also be changed programmatically via the API with the Dialing Permissions Resources.
Please note however that unlike the Voice Geographic Permissions, Messaging Geographic Permissions can not be changed with the API for security reasons.
Where can I find logs for changes in my GeoPermissions?
You can find the logs for changes in your Geo Permissions either in the Insights Audit Events Logs in Console or programmatically through the voice-geographic-permissions Resource Type via Events in the Monitor REST API.
What do I do if I notice irregular activity in my project?
If you notice any irregular activity on your account, please reach out to our Support team immediately. Twilio takes the financial security of our users seriously, but it is still the responsibility of the project owner to reach out.
Once an incident is reported, we can suspend all activity on a project or subaccount, or block a certain prefix while an investigation ensues. It is better to be safe and temporarily out of service, than risk high charges and abusive activity.