Troubleshooting issues with <Gather>

How does <Gather> work?

<Gather> works by passing data from key presses along to your application. When a user presses a key on their phone, the key press produces “DTMF”. DTMF stands for “Dual-tone multi-frequency signaling” and are the familiar sounds you hear when dialing a phone. DTMF have been standardized so that they can be understood and decoded by machines.

Timeline of a key press

  1. The user presses a key and produces DTMF tones.
  2. The call passes through several carriers. One of these carriers (not always the same one) interprets the DTMF tones and translates the audio data into structured data. This structured data is then sent parallel to, but not as part of, the audio of the call.
  3. Twilio receives structured data indicating which key was pressed. Twilio only receives structured data and does not interpret the DTMF.

By the time we reach step 3, the audible DTMF tone will have been replaced with indistinguishable clicks where the sounds used to be, so there’s no possibility that Twilio is interpreting the key presses incorrectly.

Common causes for issues with <Gather>

User Behavior

Sometimes users begin to press keys before the <Gather> has actually begun. This could especially be an issue if you have a <Say> which asks for user input before the <Gather> actually begins. It is usually a good idea to nest the <Say> which asks for input within the <Gather> to prevent this. Here is an example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather timeout="10" numDigits="1">
        <Say>Please press any key to continue.</Say>
    </Gather>
</Response>

Problems might also arise if a user presses a key too quickly for the DTMF to be interpreted.

VoIP Phone Systems

VoIP phones systems sometimes run into DTMF issues because the system uses non-standard DTMF tones by default. These problems can usually be resolved by altering the settings on the VoIP system itself. If a VoIP system provides multiple DTMF options, try testing each of these options to see which one works the best.

Google Voice

The browser based version of Google Voice has known issues with DTMF.

Environmental Factors

Any issue which causes sound to be lost or altered, such as poor reception, poor audio quality or significant background noise, can also make it difficult for carriers to distinguish between DTMF and other noise.

Carrier Issues

Very, very rarely DTMF will not be interpreted or transmitted properly by a carrier.

Troubleshooting Tips

There is no test which can be done to definitively determine where a problem with <Gather> comes from. The best approach to take is to do everything possible to isolate the issue. Try the following:

  1. Use several different phones from different carriers. If the problem is occurring reliably on multiple telephones from multiple service providers, please contact Twilio support. If the issue is happening reliably, but only on phones from a particular carrier, you might want to contact that carrier directly to report the issue.
  2. If the issue is happening intermittently, it may be due to environmental factors or the style of use from a particular user. Try to see if there is a particular user, phone or location that experiences this issue more often.

One thing which shouldn’t be overlooked when troubleshooting issues with <Gather> is the possibility that <Gather> is receiving all of the digits, but that the request which Twilio is making the URL specified in <Gather action=”"> isn’t being handled by your application. Be sure to check that action=”" is pointed to the correct location, and that that location is able to accept requests made with the method you are using.