> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pass values when a call starts

> Define dynamic variables with defaults, then send their values when a call starts: from the API, the web SDK, a batch call file or a test call.

Dynamic variables carry data from your systems into a call: the customer's name, an order number, a plan. You define each one on the agent with a default value, write it in your prompts and tools as `{{name}}`, and send the real value in `params` when you start the call. Any value you don't send falls back to its default.

## Add a dynamic variable

**1. Open Dynamic variables**

In a flow agent, click **Variables** on the canvas toolbar, then **Manage** next to **Dynamic variables**. In a single prompt agent, open **Variables**, click **Manage variables**, then **Manage** next to **Dynamic variables**.

**2. Name it**

In **Variable name**, type a snake\_case name, for example `customer_name`. Use lowercase letters, numbers and underscores, starting with a letter.

**3. Give it a default**

In **Default value**, type the value the agent uses when a call doesn't send one. **Add** stays disabled until there is a default.

**4. Save it**

Click **Add**. The variable is available in every step of a flow, and everywhere in a single prompt agent.

To rename a variable or change its default, click **Edit name** on its row. **Duplicate** copies it.

You can also start from the text: when you write `{{customer_name}}` in a flow step before the variable exists, the editor marks it as not defined. Click it and choose **Add as dynamic variable**. See [Test values](https://docs.tryhamsa.com/agents/variables/test-values.md#the-not-defined-chip).

![The Dynamic variables view with customer\_name and order\_id and their defaults, and the Add form filled in with delivery\_city and Dubai](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/variables/dynamic-variables-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=aa5ac17c555245009f33ce0230064102)

### Name rules

| Message | Cause |
| - | - |
| "Variable name is required" | The name is empty. |
| "Variable name must be in snake\_case format (lowercase, underscores allowed)" | The name has capitals, spaces, dashes, or starts with a number or underscore. |
| "Variable name already exists" | Another dynamic variable has this name. |
| "An environment variable already uses this key" | An [environment variable](https://docs.tryhamsa.com/agents/variables/environment-variables.md) has the same name. |
| "Default value is required" | You cleared the default while editing. |

## Send values from the API

Start an outbound phone call with `POST /v1/voice-agents/phone-number/call` and put the values in `params`, keyed by variable name.

```bash theme={null}
curl -X POST https://api.tryhamsa.com/v1/voice-agents/phone-number/call \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+97142345678",
    "toNumber": "+971501234567",
    "voiceAgentId": "48f7656f-098b-4c43-b165-7cfd2cc8ac30",
    "params": {
      "customer_name": "Sara",
      "order_id": "A-1042",
      "is_vip": "True"
    }
  }'
```

| Field | What it is |
| - | - |
| `phoneNumber` | Required. One of your project's phone numbers, the number the call comes from. |
| `toNumber` | Required. The number to call, starting with `+` and the country code. |
| `voiceAgentId` | The agent that takes the call. Leave it out to use the agent assigned to `phoneNumber`. |
| `params` | The values for your variables, as an object of name and value. |

The response comes back with status 201:

```json theme={null}
{
  "success": true,
  "message": "success",
  "data": {
    "jobId": "c1d7e2a4-5b3f-4e6a-9d8c-0f1a2b3c4d5e",
    "voiceAgentId": "48f7656f-098b-4c43-b165-7cfd2cc8ac30"
  }
}
```

See [Make an outbound call](https://docs.tryhamsa.com/agents/connect/outbound-calls.md) for the rest of the call options.

## Send values from the web SDK

Pass `params` to `start()` when you open a conversation from your website or app with the web SDK.

```javascript theme={null}
import { HamsaVoiceAgent } from "@hamsa-ai/voice-agents-sdk";

const agent = new HamsaVoiceAgent("YOUR_API_KEY");

await agent.start({
  agentId: "48f7656f-098b-4c43-b165-7cfd2cc8ac30",
  voiceEnablement: true,
  params: {
    customer_name: "Sara",
    order_id: "A-1042",
  },
});
```

Send every value as a string. A number or a boolean in `params` makes the SDK's start request fail validation; write `"3"` and `"True"` instead.

See [Embed on your website](https://docs.tryhamsa.com/agents/publishing/embed.md) for setting up the SDK and the widget.

## Send values from a batch call file

In a [batch call](https://docs.tryhamsa.com/agents/connect/batch-calls.md), each column of the recipient file other than the known ones becomes a variable for that recipient. Name the column exactly like the variable, in the same case.

```csv theme={null}
phone_number,name,order_id
+971501234567,Sara,A-1042
+966551234567,Omar,A-1043
```

| Column | Becomes |
| - | - |
| `phone_number` | The number to call. Required. |
| `name` | The recipient's name. It shows in the batch call's list and is passed to the agent as `{{name}}`. |
| `ignore_e164_validation` | Whether to accept a local number without a country code. |
| Any other column, like `order_id` | A variable with that name, for that recipient |

An empty cell sends nothing for that recipient, so the variable's default applies. That includes `name`.

See [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md) for every column and the phone number rules.

## Send values from a test call

When you test an agent from the editor with **Test** > **Browser call** or **Phone call**, a form asks for a value for each dynamic variable, filled in with its default ("Provide values for your dynamic variables to start the call. All variables are required."). Change the values you want to try and start the call. The form sends them as `params`, like the API does.

See [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md).

## How values are combined

For each variable, a value sent in `params` wins over the variable's default. This works key by key: a request that sends only `customer_name` keeps the defaults of all the other variables.

On the call, an [environment variable](https://docs.tryhamsa.com/agents/variables/environment-variables.md) with the same name wins over both. A value sent at call start can't replace an environment value.

## Good to know

* **Every value is a string.** If you send a number or a boolean where the API accepts one, the agent reads it as text: `true` becomes `True`, `3` becomes `3`. Compare with `{% if is_vip == "True" %}` or convert with `| int`. See [Jinja](https://docs.tryhamsa.com/agents/variables/jinja.md#every-value-is-a-string).
* **Lists and objects:** send them as JSON text, for example `"items": "[\"Tea\", \"Cake\"]"`. Text that starts with `[` or `{` is read as a list or an object, so `{{ items | join(", ") }}` gives `Tea, Cake`.
* **Keys you didn't define still work.** A `params` key that isn't a dynamic variable on the agent is accepted and can be used as `{{key}}`. Defining it gives it a default and makes it show in the editor.
* **Not sent, no default:** the variable renders empty, and the call goes on.

## Related

> [card] [Variables overview](https://docs.tryhamsa.com/agents/variables/overview.md)
>
> The kinds of variables and which value wins.

> [card] [Environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md)
>
> Values per environment, which outrank params.

> [card] [Make an outbound call](https://docs.tryhamsa.com/agents/connect/outbound-calls.md)
>
> The full outbound call API.

> [card] [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md)
>
> Columns and format for batch calls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.