DTMF events

DTMF events are fired when callers press keys on their phone keypad. These include individual key-press events and aggregated digit collection results from the play_and_get_digits command.

dtmf

Fired when the caller presses a DTMF key during the call. This event fires independently of any command — individual key presses are reported in real time during playback, recording, or any other call state.

Payload schema

Field	Type	Description
event	string	Always "dtmf". required
session_uuid	string	Unique session identifier. required
digit	string	Single DTMF character: 0-9, A-D, *, or #. required
duration_ms	integer	Key press duration in milliseconds. required

{
  "event": "dtmf",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "digit": "5",
  "duration_ms": 120
}

digits.collected

Fired when the play_and_get_digits command completes DTMF collection. This aggregates multiple key presses into a single result with a status indicating success, timeout, or failure.

Note

Individual dtmf events also fire during digit collection. Use digits.collected for the final aggregated result and dtmf events if you need real-time per-key feedback.

Payload schema

Field	Type	Description
event	string	Always "digits.collected". required
session_uuid	string	Unique session identifier. required
command_uid	string	The command_uid from the play_and_get_digits request. required
digits	string	The collected DTMF digit string. May be empty on timeout. required
terminator	string	The DTMF key that terminated collection (0-9, A-D, *, #) or empty on timeout. required
status	string	Collection result. One of success, timeout, failure, unknown. required

Collection statuses

Status	Description
success	The required number of digits was collected (or a terminator key was pressed).
timeout	The collection timed out before the minimum number of digits was received.
failure	The collection failed (e.g. channel hangup during collection).
unknown	The collection status could not be determined.

Example — success:

{
  "event": "digits.collected",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "command_uid": "collect-pin-001",
  "digits": "1234",
  "terminator": "#",
  "status": "success"
}

Example — timeout:

{
  "event": "digits.collected",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "command_uid": "collect-pin-001",
  "digits": "",
  "terminator": "",
  "status": "timeout"
}

Triggered by

• dtmf — automatic: fires on every DTMF key press during active calls.
• digits.collected — play_and_get_digits command.