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:
- The expected number of digits.
- A shorter nonempty value followed by the termination key or deadline.
- No input until the deadline.
- The termination key as the first input, including exhausted attempts.
- Cancellation and a subsequent attempt that must not reuse stale context.
The flow is correct when each case selects the transition and leaves the resultVariable value listed in Interpret the result.
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.
Related
- SIP signaling and media reference — to confirm how keypad events are negotiated and delivered
- Flow node reference — to configure the node and its transitions in Flow Designer
- Review a conversation and its result — to find the test call and inspect its transitions