> For a complete page index, fetch https://docs.synthflow.ai/llms.txt. For full documentation content, fetch https://docs.synthflow.ai/llms-full.txt.

# Variables

> Learn about the variable types available in Synthflow, including system variables, pre-call variables, collected variables, and action results.

Variables are placeholders that let your agent work with dynamic data. Use them in prompts, Custom Actions, call transfers, SIP headers, and webhook payloads by wrapping the variable name in curly braces, for example `{call_id}`.

Synthflow supports four types of variables:

| Type                                                | When available                    | How it's created                                     |
| :-------------------------------------------------- | :-------------------------------- | :--------------------------------------------------- |
| [System variables](#system-variables)               | Every call, automatically         | Provided by Synthflow                                |
| [Pre-call variables](#pre-call-variables)           | Before the conversation starts    | Passed into the agent before the conversation starts |
| [Collected variables](#collected-variables)         | During and after the conversation | Gathered from the user during the conversation       |
| [Action result variables](#action-result-variables) | After a Custom Action runs        | Returned from an external API response               |

## System variables

System variables are built-in values that Synthflow populates automatically for every call. You do not need to define them.

| Variable             | Description                                                                         |
| :------------------- | :---------------------------------------------------------------------------------- |
| `call_id`            | Unique identifier for the current call session.                                     |
| `user_phone_number`  | For inbound calls, the caller's number. For outbound calls, the recipient's number. |
| `from_phone_number`  | For outbound calls, the number your agent used to place the call.                   |
| `to_phone_number`    | For inbound calls, the number that was dialed (the number you own).                 |
| `agent_current_time` | The current time in the agent's timezone, as ISO 8601 with a UTC offset.            |

### Example

Pass system variables in a Custom Action request body to identify the call in an external system:

```json
{
  "id": "{call_id}",
  "caller": "{user_phone_number}",
  "dialed_number": "{to_phone_number}",
  "agent_number": "{from_phone_number}"
}
```

You can also reference system variables in prompts:

```text
The caller's phone number is {user_phone_number}.
```

## Pre-call variables \[#pre-call-variables]

Pre-call variables, also called custom variables, are values you pass into the agent before the conversation starts. They inject external context without requiring the agent to collect it during the conversation.

Use pre-call variables to personalize conversations with user details, CRM data, campaign context, account status, or other backend data.

### How to use pre-call variables

1. Identify the data you want to inject (for example, a company name or user role).
2. Include the data in the `custom_variables` field of your API request.
3. Reference the values in prompts, actions, transfers, SIP headers, or webhook payloads.

```json
{
  "custom_variables": {
    "Company": "Synthflow",
    "Role": "Sales Specialist"
  }
}
```

For API-specific details, see [Dynamic prompt injection](/dynamic-prompt-injection).

## Collected variables

Collected variables are values gathered from the user during the conversation after the user provides the requested information.

Use collected variables when the agent needs to remember information for later steps, such as a caller's name, email address, appointment date, issue type, or transfer reason.

### How they work

1. The agent asks for specific information.
2. The user provides the response.
3. Synthflow stores the response as a variable, for example `{user_email}` or `{appointment_date}`.
4. The variable can be used later in prompts, Branch nodes, Custom Actions, transfers, SIP headers, and webhooks.

In Flow Designer, Conversation nodes are the primary way to define collected variables. You can also use the **Variables** drawer to view available variables, see where they are used, and navigate back to their source.

### Post-call webhook payload

Post-call webhooks include collected values in the `collected_variables` field when they are available. Only variables with `collected: true` are included.

```json
{
  "collected_variables": {
    "user_name": {
      "value": "Julian",
      "collected": true
    },
    "appointment_date": {
      "value": "2025-10-28",
      "collected": true
    }
  }
}
```

For the full payload shape, see [Post-Call Webhook](/webhooks#collected-variables).

## Action result variables

Action result variables store data returned by [Custom Action](/about-custom-actions) API calls. When a Custom Action executes, the response is parsed and stored in variables you can [reference later.](#reference-action-results-in-your-prompt)

![](https://storage.googleapis.com/granular-changelog/doc-images/custom_actions_action_results.png)

### How they work

1. A Custom Action sends an API request (GET, POST, PUT, etc.).
2. The external API returns a response.
3. The response data is stored in action result variables.
4. Reference the results in prompts or pass them to other actions.

For example, if a Custom Action calls an order-status API and returns `{"status": "shipped"}`, you can reference `{status}` in your prompt or in subsequent actions.

For more details on configuring Custom Actions and using their responses, see [Custom Actions](/about-custom-actions).

### Reference action results in your prompt

In the agent **Prompt** editor, type `<` and Synthflow will list the available data of the response of your initialized custom action. You can also use the **Action results** control in the prompt toolbar.

![](https://storage.googleapis.com/granular-changelog/doc-images/custom_action_action_results_attach.png)

### In-call messaging replies

[In-Call Messaging](/in-call-messaging) actions populate a dedicated reply variable when the customer responds by text:

| Variable         | Populated by                           |
| :--------------- | :------------------------------------- |
| `sms_reply`      | A reply to an in-call SMS action.      |
| `whatsapp_reply` | A reply to an in-call WhatsApp action. |

The variable is set as soon as the reply arrives, whether the action was configured to block the agent until then or to let the call continue in the background. If no reply arrives before the call ends, the variable remains empty.

## Action placeholders and mapping \[#action-placeholders-and-mapping]

Several actions let you embed **placeholders** with angle-bracket names, for example `<customer_name>` or `<queue_ref>`, in specific configuration fields such as the **SMS message** body, **call transfer** targets or SIP headers, or the **`lead_email`** input on **real-time booking**. Each distinct name becomes an **input variable** on that action.

On [Custom Actions](/about-custom-actions#reference-every-variable-you-define), the fields that accept placeholders are the endpoint URL path, query parameters, headers, and the request body. A name you define but never reference in one of those fields does not become an input variable, and it does not appear in the action editor.

After you **attach** the action to an agent, you **map** each input to its source: values **collected during the call**, **system** fields, **pre-call variables (custom variables)**, **action results** from another step, or a fixed value you enter. These are the same families summarized in the overview table at the top of this page.

### Choose how an input variable gets its value

When an action exposes an input variable, choose how Synthflow should fill that value when the action runs.

![Input variable mapping source options](https://storage.googleapis.com/granular-changelog/doc-images/actions_mapping_choice.png)

| Source                 | Use it when                                                          |
| :--------------------- | :------------------------------------------------------------------- |
| **Collect by Agent**   | The agent should ask the user for the value during the conversation. |
| **Action Output**      | A previous action returns the value.                                 |
| **System**             | The value should come from a system variable like `{call_id}`.       |
| **Pre-Call Variables** | The value is passed into the agent before the conversation starts.   |
| **Fixed Value**        | The value is static and does not change between conversations.       |

Field-by-field setup lives in each action guide:

* [Custom Actions](/about-custom-actions#variables)
* [Call transfers](/call-transfers#variables)
* [Real-time booking](/create-a-real-time-booking-action#variables)
* [Post-call SMS](/post-call-sms#variables)

## Where to use variables \[#where-to-use-variables]

Angle-bracket placeholders on supported actions are covered in [Action placeholders and mapping](#action-placeholders-and-mapping). Variables can also be referenced in several other places across your agent configuration:

* **Prompts**: Personalize your agent's behavior, for example `"Hi {lead_name}, thanks for calling {company_name}."`.
* **Custom Actions**: Pass variables in API parameters or body fields on [Custom Actions](/about-custom-actions#variables), shape JSON with placeholders, and reuse response fields in later steps.
* **Real-Time Booking**: When you attach [real-time booking](/create-a-real-time-booking-action#variables), define variables so details the caller gives you, like `<user_name>` or `<user_email>`, flow into the booking request.
* **Call Transfers**: On [call transfers](/call-transfers#variables), define variables to capture context like `<caller_name>` or `<issue_type>` for whispers, summaries, or SIP headers.
* **Post-call SMS**: On [Post-call SMS](/post-call-sms#variables), define variables to personalize templates, for example `"Hi <customer_name>, your appointment is confirmed for <appointment_date>."`.
* **Webhooks**: Reference variables when configuring webhook payloads.
* **Flow Designer nodes**: Use variables in Conversation, Message, Branch, and Custom Action nodes in the [Flow Designer](/flow-designer).
* **SIP headers**: Pass system variables in SIP X-headers for telephony integrations, as described in [Use SIP X-Headers in Prompts, Actions & Transfers](/sip-x-headers-in-prompts).

## FAQ

#### Are all variable types available in both Flow Designer and Prompt Builder agents?

Yes. System variables, pre-call variables, collected variables, and action result variables are available in both Flow Designer and Prompt Builder agents.