DTMF collection in SIP flows

Use this reference when a SIP flow must collect keypad input or when the digits received do not match the flow's next step.

Availability: This describes the dtmf_collect node in the SIP call runtime. The call must reach that node and deliver keypad events to it. Browser keypad actions, managed-provider input messages, and pre-flow extension selection have separate handling; do not assume they use this contract. For the SIP transport prerequisite, check DTMF negotiation.

Configure the collection

Field	Meaning and effective behavior
maxDigits	Maximum collected length. The runtime uses 1 when omitted. It is not a minimum length or a validation rule.
timeoutMs	One deadline for a collection attempt, in milliseconds; default 10000. Receiving a digit does not restart the timer.
terminationKey	Optional key, such as #, that ends an attempt. It is excluded from the returned string.
resultVariable	Required flow-context key, for example menuDigits. Use a lowerCamelCase name starting with a lowercase letter and containing only letters/numbers, at most 100 characters.
maxAttempts	Default 1. Empty input ended with the termination key can start another attempt. Silence until the deadline does not use this retry loop; see the outcomes below.
prompt.media	Optional media URI passed to playback before the collector registers its digit listener. Verify prompt/input timing with your call path.
prompt.text	Text metadata; this runner does not turn it into speech. Configure actual media when an audible prompt is required.
transitions	Flow transitions that handle successful completion and the emitted signals. Include a recovery path for aborted as well as timeout.

Set a positive intended limit, deadline and attempt count. Supply resultVariable explicitly even though the runtime has a fallback name; the flow schema requires it.

Interpret the result

What happens while the node collects	Node result	Result variable
Input reaches maxDigits	Completes	Collected string
Caller presses the termination key after entering digits	Completes	Collected string, without the termination key
Deadline expires after at least one digit	Completes	Partial collected string
Deadline expires with no digits	Emits aborted immediately	Unchanged; a previous value can remain
Collection is cancelled while waiting, for example when the channel ends	Emits aborted	Unchanged
Caller presses only the termination key	Tries again if an attempt remains	No success value yet
Empty-terminator attempts exhaust maxAttempts	Emits timeout	Set to null

Current behavior: A logged collection timeout can accompany an aborted flow signal when no digits arrived. Do not connect only a timeout transition and assume it covers silence. An aborted signal alone also does not prove that the caller hung up.

A successful collection means that a nonempty string was collected, not that an account number, menu option or required length is valid. Validate the value in the following flow step. Only treat it as fresh input after a successful collection; an aborted attempt can leave an earlier value in context.

For example, with maxDigits: 4, a caller who enters 7 and then waits past the deadline produces a successful result of "7". A four-digit requirement needs a separate validation branch. If the caller enters nothing, the outcome is aborted, even when maxAttempts is greater than one.

In words: nonempty input completes and still needs validation. Silence or cancellation aborts without replacing a previous value. Only empty-terminator attempts follow the retry/exhaustion path described here.

Keep extension selection separate

Pre-flow extension selection uses a separate collector that waits for three characters, with a ten-second attempt window and a default of three attempts. Partial extension input can lead to another attempt; it does not follow the flow node's partial-input completion rule. Confirm which stage of the call is collecting before applying a timeout or retry explanation.

Verify your flow

Use a controlled test call and check the actual context value and selected transition for:

1. The expected number of digits.
2. A shorter nonempty value followed by the termination key or deadline.
3. No input until the deadline.
4. The termination key as the first input, including exhausted attempts.
5. Cancellation and a subsequent attempt that must not reuse stale context.

Use Diagnose missing or unexpected keypad input to separate transport delivery from collection and downstream validation. A received-digit log does not prove that the flow consumed a digit or that another party received it after transfer. Keep keypad values out of diagnostic reports when they could contain sensitive information.