Collect DTMF input with optional playback
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 for complete payload schemas and examples.
Authentication
Send Authorization: Bearer <app_uuid>:<api_key> using an active API key. See Authentication for details.
Path parameters
Session identifier.
Headers
Optional key for safely retrying mutating requests. An explicitly empty header is treated like omission and does not enable replay protection. See Idempotency for details.
optional client-supplied lowercase RFC-4122 v4 UUID returned as operation_uuid; platform generates one when omitted; correlation metadata distinct from Idempotency-Key.
Request
Milliseconds to wait for the first digit before timing out. Allowed range: 1000–300000 ms (1 second to 5 minutes), inclusive. Values below 1000 ms are not supported.
Maximum digits to collect. Must be >= min_digits.
DTMF terminator characters. Only # and * allowed.
Optional HTTP/HTTPS WAV or MP3 URLs to play as the prompt before collecting digits.
Response headers
Server-owned W3C Trace Context for correlating this response with support and observability data. It is present on successful and error responses. A valid incoming traceparent is linked to, but never becomes, the server-owned trace identifier.
Response
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.