Play prompt and collect DTMF digits
<Tip>
An individual `dtmf.received` event is emitted immediately for every
key press, whether or not a DTMF collection is active. It contains one
key and its `duration_ms`; it does not group digits or apply collection
rules.
Use this operation when you need a complete response. It plays the
prompt, groups the caller's keys, and applies the configured digit-count,
timeout, terminator, and regular-expression validation rules. When the
cycle ends, one `digits.collected` event reports the collected value and
outcome `status`. Individual `dtmf.received` events continue throughout
the collection.
</Tip>
**Rate limit: Per command** · **Burst:** 4 · **Refill:** 0.8 req/s
This POST has its own bucket. The cancel DELETE is configured identically, but uses a separate bucket.
Play an audio prompt and collect DTMF digits from the caller.
Configure the allowed digit count, first- and between-digit timeouts,
terminators, and optional regular-expression validation. The command
returns `202 Accepted` when queued. Store its `operation_uuid` and use
the same field on `digits.collected` to correlate the final result.
**Single-shot:** the gateway runs exactly one prompt/collect cycle and
emits one `digits.collected` carrying a `status`. The gateway never
retries on its own — **the client owns the retry loop**: inspect the
`status` field and re-issue this command with whatever prompt fits
(e.g. an "invalid PIN" prompt on `status: invalid`).
**Triggered webhook:** `digits.collected`.
For every finite prompt source, the
gateway probes with HEAD first and falls back to a ranged GET. A prompt
that cannot be prepared returns a synchronous HTTP error and emits no webhook.
Authentication
AuthorizationBearer
Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>`. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.
Path parameters
uuid
Session UUID (format {5-char-prefix}-{uuid}).
Headers
Idempotency-Key
Optional client-generated key for a mutating endpoint. It identifies one method, route, query, content type, and exact raw body within the authenticated app. Reusing it for a different request returns 422. While its record exists, a retry replays the original accepted response when available. Keys are valid for 1 hour. Allowed characters: letters, digits, dot, hyphen, underscore; max 128 characters. See the Idempotency guide.
Request
This endpoint expects an object.
prompt_files
Audio URLs to play as the prompt (http(s) only).
operation_uuid
Optional caller-supplied per-command correlation id, a bare lowercase RFC-4122 v4 UUID (no prefix). Echoed back as `operation_uuid` in the 202 ack. A later lifecycle webhook carries it only when the gateway can unambiguously associate that event with this command; the field is correlation, not proof of causation. When omitted, the gateway mints one. Not an idempotency key — request deduplication is the `Idempotency-Key` header. Invalid input (not a v4 UUID) is rejected with `400 invalid_request`.
between_digits_timeout_ms
Milliseconds to wait between digits before timing out.
first_digit_timeout_ms
Milliseconds to wait for the first digit before timing out.
max_digits
Maximum digits to collect. Must be >= min_digits.
min_digits
terminators
DTMF terminator characters. Only # and * allowed.
Allowed values:
validation
Optional input validation.
Response
Command accepted for async execution
operation_uuid
status
already_ended
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