API Overview

Keypad (DTMF)

Collect and send DTMF keypad input.
View as Markdown

Keypad input lets your application receive keypad presses from a caller or send them to a remote party on a Session. These key presses use dual-tone multi-frequency (DTMF) signals.

When to use

Use keypad input to collect menu choices or digits from callers, or to send DTMF tones to another IVR system.

For inbound input, handle dtmf.received events when each key press matters. Use Play prompt and collect DTMF digits when you need a complete response, and cancel the collection if it should end early. The completed response is delivered as a digits.collected event.

For outbound input, use Send DTMF sequence to send keys and timed waits to the remote party, such as when navigating an automated phone menu.

Lifecycle events

The platform emits DTMF (keypad tone) events when callers press keys on their phone keypad. dtmf.received reports individual key presses, and digits.collected reports aggregated results from the DTMF collection command.

Every payload schema below also includes the required aud string, which identifies the application that should receive the signed event.

dtmf.received

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

Payload schema

FieldTypeDescription
eventstringAlways "dtmf.received". Required
session_uuidstringUnique session identifier. Required
digitstringSingle DTMF character: 0-9, A-D, *, or #. Required
duration_msintegerKey press duration in milliseconds. Required
timestampstringRFC 3339 / ISO 8601 UTC timestamp at which the event was emitted (e.g. "2025-06-06T08:53:24.123Z"). Present on every webhook event. Required

For example, a dtmf.received event has this payload:

1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "dtmf.received",
4  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5  "digit": "5",
6  "duration_ms": 120,
7  "timestamp": "2025-06-06T08:53:24.123Z"
8}

Valid digit values are 0–9, A–D, *, and #. A letter-digit example:

1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "dtmf.received",
4  "session_uuid": "acW68-...",
5  "digit": "A",
6  "duration_ms": 100,
7  "timestamp": "2025-06-06T08:53:24.500Z"
8}

digits.collected

Fired once when a DTMF collection command finishes its single prompt-and-collect cycle. It aggregates the key presses into a single result with a status describing the outcome. The command never retries on its own — your app inspects status and decides whether to re-prompt. See Play prompt and collect DTMF digits.

Event filtering. dtmf.received and digits.collected are independent webhook events, and by default both are delivered. Individual dtmf.received events also fire during digit collection. Use digits.collected for the final aggregated result and dtmf.received events if you need per-key feedback as each digit arrives.

Payload schema

FieldTypeDescription
eventstringAlways "digits.collected". Required
session_uuidstringUnique session identifier. Required
operation_uuidstringThe operation_uuid echoed from the 202 acknowledgement of the DTMF collection request. Required
digitsstringThe collected DTMF digit string. May be empty on timeout. Required
terminatorstringThe DTMF key that terminated collection (0-9, A-D, *, #) or empty on timeout. Required
statusstringOutcome of the prompt-and-collect cycle. One of: success, no_input, partial_then_timeout, invalid, failure, cancelled, unknown. Required
timestampstringRFC 3339 / ISO 8601 UTC timestamp at which the event was emitted (e.g. "2025-06-06T08:53:24.123Z"). Present on every webhook event. Required

Collection statuses

StatusDescription
successAt least min_digits digits were collected and any configured validation passed. Collection may have ended by a terminator key, by reaching max_digits, or by the between_digits_timeout_ms timer expiring once at least min_digits digits had already been entered — all are successes; the digits are delivered either way. With min_digits: 0, a caller who presses only a terminator key submits an empty entry: status is success, digits is empty, and terminator carries the key that ended collection.
no_inputThe caller entered no digits at all. digits is empty.
partial_then_timeoutThe caller entered some digits but fewer than min_digits, then stopped pressing keys and the inter-digit timer (between_digits_timeout_ms) expired before reaching min_digits. digits holds the partial input.
invalidDigits were collected but failed the configured validation.regex. digits holds what was entered.
failureThe collection failed before any outcome could be classified — the caller hung up before or during the prompt or collection, the call had not yet been answered, or the prompt file could not be played. The digits field is usually empty, but may contain partial input that was collected before the failure.
cancelledThe collection was cancelled by the DTMF collection cancellation endpoint. If the command was already running when the DELETE arrived, digits holds whatever partial input had been collected so far (which may be empty if the caller had not yet pressed a key). If the command was still queued behind another command and had not started, digits is always empty.
unknownAn unexpected outcome. Log it and investigate; do not retry the command.

Example — success:

1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "digits.collected",
4  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5  "operation_uuid": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
6  "digits": "1234",
7  "terminator": "#",
8  "status": "success",
9  "timestamp": "2025-06-06T08:53:24.123Z"
10}

Example — no input:

1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "digits.collected",
4  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5  "operation_uuid": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
6  "digits": "",
7  "terminator": "",
8  "status": "no_input",
9  "timestamp": "2025-06-06T08:53:24.123Z"
10}

Example — failure with partial digits:

1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "digits.collected",
4  "session_uuid": "acW68-...",
5  "operation_uuid": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
6  "digits": "12",
7  "terminator": "",
8  "status": "failure",
9  "timestamp": "2025-06-06T08:53:24.123Z"
10}

Example — cancelled:

1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "digits.collected",
4  "session_uuid": "acW68-...",
5  "operation_uuid": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
6  "digits": "",
7  "terminator": "",
8  "status": "cancelled",
9  "timestamp": "2025-06-06T08:53:24.123Z"
10}

Triggered by

These events are produced by the following triggers: