Variables

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 three types of variables:

Flow Designer agents also support collecting variables during conversations and managing them through the variable drawer. See Variables in Flow Designer for details.

System variables

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

Usage example

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

1
{
2
  "id": "{call_id}",
3
  "caller": "{user_phone_number}",
4
  "dialed_number": "{to_phone_number}",
5
  "agent_number": "{from_phone_number}"
6
}

You can also reference system variables in prompts:

The caller's phone number is {user_phone_number}.

Custom variables

Custom variables are key-value pairs passed through the API when you start a call. They inject external data into your agent’s prompt without requiring the agent to collect it during the conversation.

How to use custom 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 your agent’s prompt.

1
{
2
  "custom_variables": {
3
    "Company": "Synthflow",
4
    "Role": "Sales Specialist"
5
  }
6
}

For more details, see Custom variables and Dynamic prompt injection.

Action result variables

Action result variables store data returned by Custom Action API calls. When a Custom Action executes, the response is parsed and stored in variables you can reference later.

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.

Where to use variables

Variables can be referenced in several 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 request parameters or body fields to integrate with external systems.
• Call transfers: Include phone number variables in SIP headers or transfer configurations.
• Webhooks: Reference variables when configuring webhook payloads.
• Flow Designer nodes: Use variables in Conversation, Message, Branch, and Custom Action nodes. See Variables in Flow Designer for details.
• SIP headers: Pass system variables in SIP X-headers for telephony integrations. See Use SIP X-Headers in Prompts, Actions & Transfers for details.