Collect DTMF input with optional playback

View as Markdown
**Rate limit: Per command** · **Burst:** 4 · **Refill:** 0.8 req/s Collect a complete DTMF response from the caller and optionally play audio prompts first. The operation groups the caller's keys and applies the configured digit-count, timeout, terminator, and regular-expression validation rules. The platform validates and prepares every prompt URL before admitting the command. An unavailable prompt returns a synchronous HTTP error and does not trigger a webhook. A `202 Accepted` response means that the command was queued. The application stores its `operation_uuid` and matches it to the same field in the terminal `digits.collected` event. The platform runs exactly one prompt-and-collect cycle and emits one `digits.collected` event with the collected value and outcome `status`. It does not retry the cycle. The application inspects `status` and submits another command when needed, such as a command with an invalid-PIN prompt after `status: invalid`. The platform also emits a `dtmf.received` event immediately for every key press, whether or not a collection is active. Each event contains one key and its `duration_ms`; it does not group digits or apply collection rules. These events continue during a collection. **Triggered webhook:** `digits.collected`. This POST and its cancel DELETE each use a separate rate-limit bucket with the same configuration. See [Keypad input lifecycle events](/api/keypad-input#lifecycle-events) for complete payload schemas and examples.

Authentication

AuthorizationBearer
Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>` using any active key in the app's collection. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.

Path parameters

uuidstringRequired

Session identifier.

Headers

Idempotency-KeystringOptionalformat: "^[a-zA-Z0-9._-]+$"<=128 characters
Optional key for safely retrying mutating requests. See [Idempotency](https://voice-platform.docs.buildwithfern.com/idempotency) for details.
Operation-IdstringOptionalformat: "uuid"

optional client-supplied lowercase RFC-4122 v4 UUID returned as operation_uuid; platform generates one when omitted; correlation metadata distinct from Idempotency-Key.

Request

This endpoint expects an object.
between_digits_timeout_msintegerRequired100-10000
Milliseconds to wait between digits before timing out.
first_digit_timeout_msintegerRequired1000-300000
Milliseconds to wait for the first digit before timing out.
max_digitsintegerRequired1-128

Maximum digits to collect. Must be >= min_digits.

min_digitsintegerRequired0-128
terminatorslist of enumsRequired

DTMF terminator characters. Only # and * allowed.

Allowed values:
prompt_fileslist of stringsOptional

Optional HTTP/HTTPS WAV or MP3 URLs to play as the prompt before collecting digits.

validationobjectOptional
Optional input validation.

Response

Command accepted for async execution
operation_uuidstringformat: "uuid"
statusenum
already_endedtrueOptional

Optional. Set to true on idempotent terminal commands when the session was already in a terminal state at the time the request was received. Absent otherwise.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error