# User Input

The User Input component captures the DTMF digits (Dual-Tone Multi-Frequency: the tones a phone sends when the caller presses keys) that a caller keys in and saves them for the rest of the flow to use. It works hand in hand with the Condition component: collect what the caller enters here, then branch on that value further down the flow. You decide when collection stops, after a digit or response timeout, or when the caller presses an end key, and you can play a prompt or a spoken message to tell them what to enter.

![The User Input component on the call-flow canvas](/images/pbx/user-input-component-cfd.png)

## Prompt types you can play

You can front the input with any of three prompt types.

| Prompt type | What it plays |
| --- | --- |
| Custom Prompt | An existing custom prompt, or a new one you record from an extension or upload as an audio file. |
| Music on Hold (MoH) | A hold-music track already saved on the system. |
| Text to Speech (TTS) | Text you type, spoken back in the language and voice style you pick. |

:::note
Music on Hold has to exist before you can select it. Set it up under **PBX Settings > Voice Prompt > Music on Hold** first.

![Picking a saved hold-music track for the component](/images/pbx/moh-call-flow.png)
:::

:::note
Text to Speech is only available once the feature is switched on. Turn it on under **Integrations > AI**.

![Enabling the text-to-speech integration](/images/pbx/enable-tts-cfd.png)
:::

## End keys

An end key lets the caller signal that they have finished entering digits. You can use `#`, `*`, a numeric key, or no key at all. Set it under **Call Flow Designer > Options**.

:::note
With no end key set, the caller only advances to the next component when their entry matches or when a timeout is reached.
:::

![Choosing the end key in Call Flow Designer options](/images/pbx/endkey-cfd.png)

## Configure the component

1. Add the User Input component to your call flow, then click it to open its settings.

   ![Opening the User Input component to begin configuration](/images/pbx/user-input-cfd.png)

2. Optional: add a prompt or a spoken message to tell callers what to enter. Follow the section below that matches the prompt type you want.

### Play a custom prompt

![Selecting one or more custom prompts for the input](/images/pbx/custom-prompt-initial-action.png)

1. Click **Custom Prompt**.
2. Choose the prompt or prompts to play.

   :::note
   You can add up to **5** custom prompts.
   :::

   - To reuse an existing prompt, pick it from the **Prompt** list.
   - To add a new one, click **Record New** to record from an extension, or **Upload** to add an audio file.

     :::note
     New prompts are saved under **PBX Settings > Voice Prompt > Custom Prompt**.
     :::

3. Optional: to repeat the prompt(s) continuously, select **Enable Loop Playback**.

   :::caution
   The loop is dropped if the next connected component carries its own prompt: that prompt overrides it. This is easy to miss when a downstream component seems to ignore the prompt you set to loop.
   :::

### Play music on hold

![Selecting a saved hold-music track for the input](/images/pbx/select-moh-initial-action.png)

1. Select **Music on Hold**.
2. Pick a saved track from the **Music on Hold** list.

:::caution
The hold music is dropped if the next connected component carries its own prompt: that prompt overrides the hold music.
:::

### Play a text-to-speech message

![Entering text and choosing a voice for the input prompt](/images/pbx/tts-prompt.png)

1. Select **Text to Speech**.
2. Write the message and choose its voice style. Both static and dynamic text are supported.

   - **Static text**: type the message straight into the **Text** field.
   - **Dynamic text**: type the message and insert placeholders backed by [variables](/pbx/call-flow-designer-guide/constants-and-variables-in-cloud-voice-cfd-expression/), so the wording is assembled at call time. You can also set how long the system may take to generate the speech and where to route the caller if that limit is hit.

     **Example:**

     ![A dynamic text-to-speech message assembled from variables](/images/pbx/cfd-tts-example.gif)

   The generated speech is stored on the system and synced to **PBX Settings > Voice Prompt > Custom Prompt**.

3. Optional: to control what happens when the speech takes too long to generate, select **TTS Response Timeout**, then attach the next components to the **TTS Playback Success** and **TTS Response Timeout** branches.

   :::note
   Leave the timeout branch unset and a caller who hits the limit simply moves on to the next component without hearing anything.
   :::

### Set the input timeouts

Tell the component how long to keep listening for digits.

![Setting the digit and response timeouts for user input](/images/pbx/userinput-timeout.png)

- **Digit Timeout(s)**: how long to wait for the caller to key in the next digit. Choose a value from the list, or type one between 1 and 9999.
- **Component Response Timeout(s)**: how long to wait for the caller to do anything at all. Choose a value from the list, or type one between 1 and 9999.

:::tip
Give callers enough time on both timeouts. If a timeout is reached before the caller finishes keying in their digits, the component ends with `UserInputResult.Timeout` and the call follows the timeout path instead of the option the caller was trying to reach.
:::

### Finish

Click **Confirm** in the bottom-right corner. The prompt you chose now shows on the component.

![The configured prompt shown on the User Input component](/images/pbx/userinput-display.png)

## Component variables

Every User Input component stores the caller's entry in variables. Expression-aware components such as [Condition](/pbx/call-flow-designer-guide/condition/) can read those values to decide where the call goes next.

:::note
A single call flow can hold several User Input components, so each one is numbered in the order it was added (User Input 1, User Input 2, and so on). Include the matching index in the variable to read the component you actually mean.
:::

| Variable | Type | Description | Example |
| --- | --- | --- | --- |
| `$UserInput{index}.result` | String | How the component finished. `UserInputResult.Timeout` means the caller entered no digits before the timeout and was sent to the timeout destination; `UserInputResult.ValidOption` means the caller pressed a valid key and was sent to the matching destination. | `$UserInput1.result(STRING)=UserInputResult.Timeout` |
| `$UserInput{index}.ttsResult` | String | The text-to-speech outcome. `UserInputTTSResult.Success` means the text was converted and played to the caller; `UserInputTTSResult.Timeout` means it was not generated in time, so the caller moved straight on with no prompt. | `$UserInput1.ttsResult(STRING)=UserInputTTSResult.Success` |
| `$UserInput{index}.userInput` | String | The DTMF digits the caller pressed, not counting the end key (`#` or `*`). | `"2"` |

## Connect the component

A User Input component connects to **one** downstream component, or **two** when **TTS Response Timeout** is on (one for success, one for the timeout). You can connect any of the components below.

| Component | What it does |
| --- | --- |
| [Prompt](/pbx/call-flow-designer-guide/prompt/) | Plays an audio prompt or text-to-speech message to the caller. |
| [Business Hours](/pbx/call-flow-designer-guide/business-hours/) | Routes calls to different destinations based on the time of day. |
| [Menu](/pbx/call-flow-designer-guide/menu/) | Offers callers a set of options and routes on the DTMF digit they press. |
| [User Input](/pbx/call-flow-designer-guide/user-input/) | Collects DTMF digits from the caller, usually paired with Condition to route on what was entered. |
| [Language](/pbx/call-flow-designer-guide/language/) | Switches the system-prompt language for the components that follow. |
| [Record](/pbx/call-flow-designer-guide/record/) | Starts recording once the caller connects to another party, with optional notice prompts, or disables recording for a call that would otherwise be recorded. |
| [Dial by Number](/pbx/call-flow-designer-guide/dial-by-number/) | Lets callers dial a number directly to reach their destination. |
| [Dial by Name](/pbx/call-flow-designer-guide/dial-by-name/) | An end component that lets callers reach a user by typing the first three letters of their name. |
| [Transfer](/pbx/call-flow-designer-guide/transfer/) | An end component that hands the caller to a set destination, with an optional prompt announcing the transfer. |
| [Hang Up Call](/pbx/call-flow-designer-guide/hang-up-call/) | An end component that disconnects the caller. |
| [Condition](/pbx/call-flow-designer-guide/condition/) | Routes calls according to logical expressions. |
| [Loop](/pbx/call-flow-designer-guide/loop/) | Repeats a group of components a set number of times or until a condition is met. |
| Internal Data Ops | Reads from and writes to the PBX's built-in database. See [Get Extension Presence Status](/pbx/call-flow-designer-guide/get-extension-presence-status/), [Set Extension Presence Status](/pbx/call-flow-designer-guide/set-extension-presence-status/), [Get Queue Agent](/pbx/call-flow-designer-guide/get-queue-agent/), [Get Queue Info](/pbx/call-flow-designer-guide/get-queue-info/), [Get Agent Status](/pbx/call-flow-designer-guide/get-agent-status/), [Set Agent Status](/pbx/call-flow-designer-guide/set-agent-status/), [Get System Info](/pbx/call-flow-designer-guide/get-system-info/), [Get System Capacity](/pbx/call-flow-designer-guide/get-system-capacity/), [Get Extension Info](/pbx/call-flow-designer-guide/get-extension-info/), and [Get Company Contact Info](/pbx/call-flow-designer-guide/get-company-contact-info/). |
| [Email Sender](/pbx/call-flow-designer-guide/email-sender/) | Sends email for real-time notifications, alerts, or user-specific information. |
| [Database Access](/pbx/call-flow-designer-guide/database-access/) | Runs SQL against a database mid-call to read or update data. |
| [HTTP Request](/pbx/call-flow-designer-guide/http-request/) | Sends HTTP requests to external servers to exchange data with third-party services. |