Webhooks

DTMF events

Handle individual keypad presses and collected digit input.
View as Markdown

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.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
1{
2  "event": "dtmf.received",
3  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
4  "digit": "5",
5  "duration_ms": 120,
6  "timestamp": "2025-06-06T08:53:24.123Z"
7}

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

1{
2  "event": "dtmf.received",
3  "session_uuid": "acW68-...",
4  "digit": "A",
5  "duration_ms": 100,
6  "timestamp": "2025-06-06T08:53:24.500Z"
7}

digits.collected

Fired once when a play_and_get_digits 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.

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.

Event filtering. dtmf.received and digits.collected are independent webhook events. By default both are delivered.

Payload schema

FieldTypeDescription
eventstringAlways "digits.collected". Required
session_uuidstringUnique session identifier. Required
operation_uuidstringThe operation_uuid echoed from the 202 ack of the play_and_get_digits 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 cancel play_and_get_digits 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  "event": "digits.collected",
3  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
4  "operation_uuid": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
5  "digits": "1234",
6  "terminator": "#",
7  "status": "success",
8  "timestamp": "2025-06-06T08:53:24.123Z"
9}

Example — no input:

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

Example — failure with partial digits:

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

Example — cancelled:

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

Triggered by

These events are produced by the following triggers: