Unfortunately, it's not possible to comprehensively document every variance of call behavior to all possible destinations. In addition to being a herculean effort, the document would be out-of-date and inaccurate almost as soon as it was published due to a constantly shifting landscape of underlying carrier agreements, government regulatory requirements, and partner routing changes; however, this document attempts to describe at a high level the types of issues commonly encountered when placing calls to non-local destinations, and provide mitigation strategies when available.
Dialing toll-free numbers, and using toll-free numbers as caller ID are common sources of call delivery failures. Toll-free destination carriers can choose the types of calls they want to accept and can filter this acceptance based on country of origin, the location of terminating carrier, originating caller ID, etc.
For example, you may not be able to call a UK toll-free number from an international (non-UK) caller ID; this is due to the price structure of toll-free calls where the receiving party is responsible for the cost of the call. Changing the caller ID to a UK number may improve deliverability, but it’s not guaranteed.
Twilio's recommendation is to not use toll-free numbers as caller ID on outbound calls, and when investigating delivery issues to toll-free destinations, try a number of caller ID permutations; e.g. use a caller ID from the destination country, use a caller ID from the UK, etc.
Due to local regulations and interconnect agreements between carriers, caller ID preservation cannot be guaranteed to all destinations. Some countries require caller ID mutation to ensure delivery, and some countries append or prepend additional digits to the caller ID string for their own purposes.
Some destinations will not allow a local number to be used as a caller ID (in-country format) for calls placed from outside the country and others prohibit using local caller ID for calls placed inside the country. Local, in-country caller ID in the US and Europe has a higher chance of being preserved than calls to other destinations. The best way to preserve caller ID is by using the international E.164 format for your caller ID.
ANONYMOUS, or other text in the caller ID will be translated into numeric representations of the characters; see this FAQ for more detail.
In order to prevent fraud, some countries and local providers have hard-coded a maximum call length that is less than the Twilio platform maximum call duration (currently four hours). These limits are typically 30, 60, or 90 minutes, but can vary depending on the call destination and routing. If you notice that all of your calls to a specific country are getting “dropped” at exactly 60 minutes, chances are you are running into one of these duration timers.
Numbers outside the US and Europe often have low simultaneous call limitations; meaning you might not be able to have large numbers of calls happening to or from a particular number at the same time. In general, toll-free numbers are designed to provide a higher concurrent call capacity. More information can be found in our article Toll-free phone number restrictions and limitations.
Media Timeouts (Call Silence)
The telecommunications industry standard silence timeout for audio streams is 60 seconds, though some partners may have lower or higher thresholds, and different partners may have different thresholds in different locations.
For example, when using the
<Record> verb, Twilio does not send back a silent stream to the inbound carrier; in most cases, this is fine, but some carriers are highly sensitive to the appearance of one-way audio on their calls, and even though a single stream should be enough to maintain the session, they will aggressively tear down the call. To avoid calls with <Record> being torn down by the carrier, try the following:
<Dial record="true" action="record_done"><Conference waitUrl="">record</Conference></Dial>
Using a blank Conference waitUrl here will return a silent stream, and should help prevent your call being disconnected for one-way audio.
Unsupported Dialing Destinations
Twilio cannot deliver calls to Premium Rate Numbers, shared cost lines, local service, or emergency numbers.
Third Party VoIP Service Providers
Similar to how Twilio cannot guarantee 100% reachability to all destinations, other VoIP providers cannot guarantee 100% reachability to all destinations, which may include some of Twilio's numbers. This could cause some calls to fail without an attempt being logged with Twilio, as the third party VoIP provider does not have proper routes set up. In these cases, the calling party needs to work with their VoIP provider directly, and have them open up routes to the required Twilio numbers. This may not always be possible, so your results will vary depending on number, provider and/ or region.