Skip to main content

Overview

Audio streams carry DTMF (touch-tone) digits in both directions:

When to use DTMF on a stream

  • Keypad input to a voice agent: let callers press keys (“press 1 for sales”) while your agent is listening.
  • IVR navigation: have an AI agent on an outbound call work through another company’s phone menu.
  • PIN and account entry: let your agent enter account numbers, PINs, or extensions on the caller’s behalf.
  • Hybrid input: accept either speech or keypresses for the same question.

Receive keypresses: dtmf event

When a key is pressed on the call, Vobiz sends a dtmf event over the WebSocket. You don’t need to configure anything to receive it.
dtmf event
dtmf events are sent on every active stream on the call, including streams with bidirectional="false". If a call has more than one stream, each stream receives its own dtmf event for the same keypress.

What to know about received digits

  • Keypresses still reach the call flow. A dtmf event is a copy. The same digit still goes to anything else listening on the call, such as a <Gather> running after the stream started.
  • Out-of-band DTMF only. Vobiz reports keypresses that arrive as RFC 2833 telephone events or SIP INFO, which is how almost all carriers and phones send them. Tones that exist only inside the audio (inband DTMF) are not reported as dtmf events. You still receive them as sound in media frames.
  • Only while the stream is connected. Keys pressed before the WebSocket connects, or after the stream stops, are not delivered.
  • No duration. Each event marks one keypress. Vobiz does not report how long the key was held.

Send digits: sendDTMF event

Send a sendDTMF event to play DTMF digits into the call. Vobiz sends them to the other party on the call: on an outbound call to an IVR, the IVR receives them, and on an inbound call, the caller hears them.
Prerequisite: sendDTMF requires bidirectional="true" on the <Stream> element. On a unidirectional stream it is rejected.
sendDTMF event
Digits are sent one after another at standard DTMF timing, the same way as the Send Digits API. Vobiz does not send an acknowledgment when the digits have been sent. If you need to wait for an IVR to respond, listen for its next prompt in the media frames.

Rejected messages

If a sendDTMF message is invalid, Vobiz sends no digits and replies with an incorrectPayload event that contains the message you sent:
incorrectPayload event
A sendDTMF message is rejected when:
  • the stream is not bidirectional,
  • dtmf is missing or empty,
  • dtmf is longer than 99 characters, or
  • dtmf contains a character other than 0–9, *, #, A–D. Pause characters (w, W) and duration suffixes (@500) are not supported.
incorrectPayload is sent only for the first invalid message on a stream, whatever the command. Later invalid messages are dropped without a reply, so validate digits in your application before sending them.

Things to know when sending digits

  • Sent digits are not echoed back. Digits you send with sendDTMF do not produce dtmf events on your stream.
  • Pace multi-step menus yourself. Send one menu choice, wait for the IVR’s next prompt, then send the next. Sending a whole sequence at once can outrun an IVR that is still playing a prompt.
  • Long digit strings take time to play. Each digit takes a fraction of a second, so a 16-digit account number takes several seconds to finish.

Implementation examples

Node.js

Handle keypresses and navigate an IVR

Python

Handle keypresses and send digits with asyncio