Dynamic variables: default values and the on_missing setting

agents/build/configuration.mdx

@@ -59,7 +59,7 @@
   - `low` (**Hard to interrupt** in the Builder): The agent stops only for a firm, worded interjection, talking through background noise and short acknowledgements.
   - `balanced` (default): Interrupts on normal speech.
   - `high` (**Easy to interrupt**): The agent stops on the caller's first word.
 - `conversation.interruption_ignore_phrases` (up to 50 entries of 40 characters): Backchannels such as `"uh-huh"` or `"okay"` that never interrupt the agent when the caller says only them. Matching ignores case and punctuation. Send `[]` to clear the list.
 
 ### Call duration
 
@@ -77,7 +77,7 @@
 
 `conversation.timezone` is the default IANA timezone (like `Asia/Tokyo`) the agent uses for dates and times in conversation. Leave it empty for **automatic**: each session follows the caller's device or phone number, falling back to UTC. Set one when your agent serves a single region regardless of who calls. A per-session `timezone` on the [session request](/agents/build/time-timezone) overrides this. See [Time & timezone](/agents/build/time-timezone) for the full resolution order.
 
 ## Autosave and publishing
 
 There is no Save button. Each change is written to the agent's draft moments after you stop editing, and the **Saving… / Saved** indicator at the bottom-left of the page shows the current state. If a save fails, the Builder tells you and keeps your pending edits so nothing is lost.
 
@@ -106,7 +106,7 @@
     "voice_id": "802e3bc2b27e49c2995d23ef70e6ac89",
     "speaking_language": "en"
   },
   "asr": {
     "model": "deepgram:nova-3",
     "multilingual": false,
     "strict_language": false,
@@ -150,12 +150,13 @@
 |---|---|---|
 | `prompt` | System prompt and first-message settings | This page |
 | `voice` | Voice profile, speaking language, and expressive mode | [Voice & language](/agents/build/voice-language) |
 | `asr` | Speech recognition model, multilingual recognition, strict language, and recognition keyterms | [Voice & language](/agents/build/voice-language#speech-recognition-model) |
 | `conversation` | Call duration, turn-taking, interruption behavior, timezone, and storage | This page; storage in [Conversation history](/agents/monitor/conversation-history#what-gets-stored) |
 | `tools` | Attached webhook tools and system tool switches | [Tools](/agents/build/tools) |
 | `knowledge_base` | Attached knowledge sources | [Knowledge base](/agents/build/knowledge-base) |
 | `analysis` | Post-call summary, data fields, and success criteria | [Post-call analysis](/agents/monitor/post-call-analysis) |
 | `webhooks` | Post-call webhook delivery and the inbound call webhook | [Webhooks](/agents/monitor/webhooks) |
+| `variables` | Default values for the `{{placeholders}}` in the configured text and what a placeholder without a value does | [Dynamic variables](/agents/build/dynamic-variables#default-values) |
 | `llm` | Conversation model settings, including a custom LLM endpoint | [Custom LLM](/agents/build/custom-llm) |
 
 ## Going further

agents/build/dynamic-variables.mdx

@@ -33,7 +33,7 @@
 and they are on the {{plan}} plan. Greet them by name.
 ```
 
 Pass values as a flat object of strings, numbers, or booleans. Variable names must match `[A-Za-z][A-Za-z0-9_]*` (no hyphens or dots; the dotted `system.*` names are reserved for [system variables](#system-variables)), string values are capped at 100,000 characters, and a request can carry at most 500 variables totaling 1 MiB as UTF-8 JSON. Violations reject session creation with `422`:
 
 <CodeGroup>
 ```bash API (curl)
@@ -61,8 +61,34 @@
 ```
 </CodeGroup>
 
+### Default values
+
+A placeholder is resolved in this order: the value supplied for the session, then the default configured on the agent. What happens when neither exists is set by `on_missing`:
+
+| `on_missing`       | A placeholder with no value                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| `keep` (default)   | Stays in the text as written, visible to the model and spoken on a fixed first message       |
+| `empty`            | Renders as empty text                                                                       |
+| `reject`           | Session creation fails with `422 Missing dynamic variables: ...` and an inbound call is not connected |
+
+Set both in the **Dynamic variables** sheet of the agent's Configuration page (the **Default values** link under the system prompt), or through the `variables` section of the config API. The defaults map replaces as a whole on every update, and names follow the same rules as `dynamic_variables`:
+
+```bash
+curl --request PATCH https://api.fish.audio/v1/agent/agents/YOUR_AGENT_ID/config \
+  --header "Authorization: Bearer $FISH_API_KEY" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "variables": {
+      "defaults": { "customer_name": "there", "plan": "Free" },
+      "on_missing": "empty"
+    }
+  }'
+```
+
+With these defaults, a session that sends only `{"plan": "Pro"}` renders the first message `Hi {{customer_name}}, welcome to the {{plan}} plan.` as `Hi there, welcome to the Pro plan.`
+
 <Warning>
-Placeholders with no matching variable are **not** removed: the literal `{{variable_name}}` text stays in the prompt, visible to the model. Make sure every placeholder in your configuration has a value at session creation.
+By default a placeholder with no session value and no default stays as written, so `Hi {{customer_name}}, welcome.` is spoken braces and all on a fixed first message. For text that is spoken word for word, give every placeholder that can go unfilled a default that reads well on its own, or set `on_missing` to `empty` (`Hi , welcome.`) or `reject`. A fixed first message that renders to nothing but whitespace is dropped and the agent opens with its generic greeting instead.
 </Warning>
 
 Variables fill placeholders in the configured text. To replace whole configuration fields for a session (the prompt itself, the opener, voice, language), use [overrides](/agents/deploy/authenticated-sessions#overrides) on the same request; `{{placeholders}}` render inside overridden text too.
@@ -95,7 +121,7 @@
 ```
 
 <Tip>
 In `agentId` mode, values arrive from the end user's browser. Treat them as untrusted input, and use `sessionToken` mode when personalization must come from data only your backend knows.
 </Tip>
 
 ### Custom variables in webhook tools
@@ -106,17 +132,17 @@
 https://ehr.example.com/patients/{{patient_id}}/appointments?clinic={{clinic_id}}
 ```
 
 - In the URL the value is URL-encoded, like argument values. In header values and the body template it is inserted as is. Numbers render as written, booleans as `true` or `false`.
 - When the tool declares an argument with the same name as a custom variable, the argument wins: that placeholder is filled from what the agent supplies.
 - A placeholder with no value renders as an empty string in the request, unlike in the prompt, where it stays visible.
 
 <Warning>
 On a [public agent](/agents/deploy/public-agents) the browser supplies custom values, so anyone can start a session with any `patient_id`. When a templated value identifies a person, don't let it authorize access to their data on its own: create sessions from your backend (`sessionToken` mode), or let the inbound call webhook supply it on phone calls.
 </Warning>
 
 ## System variables
 
 The platform fills a handful of `{{system.*}}` placeholders itself, on every session. You cannot supply or override them: the names you pass in `dynamic_variables` cannot contain a dot, so the two namespaces never collide.
 
 | Variable | Value | Notes |
 |---|---|---|
@@ -172,12 +198,12 @@
 A reference to a system variable that does not exist (`{{system.foo}}`) is rejected with `422` when you save the configuration or the tool, and when you send it in session overrides. The error lists the available names.
 
 <Note>
 There is no `system.session_id`. The configuration is rendered before the session receives its id, so the id cannot be templated into it. Read it from the `POST /v1/agent/sessions` [response](/agents/deploy/authenticated-sessions), the SDK's `connect` event, or the `session` object in [webhooks](/agents/monitor/webhooks).
 </Note>
 
 ## World context
 
 The agent knows the current date and time without any variable. The platform states the date and the session's timezone at the start of every session and refreshes the time on every turn, so "tomorrow morning" or "next Tuesday" resolve correctly even in a long conversation. You don't need a custom `{{today}}` or `{{now}}`, and there is no `system.now`: variables render once, when the session is created, so a templated time would be stale from the first reply onward. When you want the date or timezone as text in a template, for example in a webhook tool URL, use the [`system.today` and `system.timezone`](#system-variables) system variables.
 
 See [Time & timezone](/agents/build/time-timezone) for how the timezone is resolved and how to turn the injection off for a session (`world_context: false`).
 

agents/monitor/webhooks.mdx

@@ -105,16 +105,16 @@
     "branch_id": "b7d4…",
     "source": "phone",
     "status": "completed",
     "end_reason": "user_hangup",
     "conversation_started_at": "2026-07-23T12:01:12Z",
     "conversation_ended_at": "2026-07-23T12:04:16Z",
     "duration_seconds": 184,
     "end_user_id": "customer-42",
     "metadata": { "order_ref": "SO-1042" },
     "agent_name": "Support agent",
     "config_hash": "sha256:9c41…"
   },
   "ended_reason": "user_hangup"
 }
 ```
 
@@ -280,14 +280,14 @@
 | Fan-out   | Every configured endpoint receives every event                                                                    |
 | Guarantee | At-least-once, per endpoint                                                                                       |
 | Timeout   | 10 seconds per attempt                                                                                            |
 | Retries   | 2 after the first attempt (3 attempts total) per endpoint, with backoff of 1s / 5s, then that delivery is dropped |
 | Ordering  | `phone_call.dial_finished` (outbound only) before `call.ended` before `call.analyzed` for the same session        |
 
 Endpoints are delivered in parallel and independently: each gets its own attempts, its own retry budget, and its own signature keyed with its own secret. An endpoint that is down and exhausts all three attempts has no effect on the others.
 
 Respond with a `2xx` status within the timeout; a `500` response or a timed-out request counts as a failed attempt. Acknowledge first and process asynchronously. Slow handlers burn their own retry budget.
 
 **Idempotency.** At-least-once delivery means the same event can arrive more than once. Retries of one delivery carry an identical body, so dedupe `call.ended` and `phone_call.dial_finished` on (`event`, `session.id`), and `call.analyzed` on (`event`, `session.id`, `analysis.finished_at`). The extra element matters because a skipped or failed analysis can be re-run from the console: the recovered result arrives as a fresh `call.analyzed` with a newer `finished_at`, superseding the earlier one.
 
 <Note>
   [Preview calls](/agents/test/preview-calls) made from the Builder never
@@ -341,11 +341,11 @@
 }
 ```
 
 `caller_number` and `dialed_number` are E.164. `caller_number` is an empty string when the carrier withholds the caller's number, and `twilio_call_sid` is empty when the call did not come through a Twilio number.
 
 ### Response
 
 Respond with a `2xx` status and a JSON object whose `dynamic_variables` follow the same rules as on session creation: names match `[A-Za-z][A-Za-z0-9_]*`, values are strings (up to 100,000 characters), numbers, or booleans, and at most 500 entries totaling 1 MiB are read.
 
 ```json Response
 {
@@ -357,7 +357,7 @@
 }
 ```
 
-An entry that breaks a rule is dropped on its own; the call still connects with the rest. Other fields in the response are ignored, so the contract can grow without breaking deployed endpoints. Placeholders that receive no value stay in the text as written, as described under [dynamic variables](/agents/build/dynamic-variables#custom-variables).
+An entry that breaks a rule is dropped on its own; the call still connects with the rest. Other fields in the response are ignored, so the contract can grow without breaking deployed endpoints. A placeholder that receives no value takes the agent's configured [default value](/agents/build/dynamic-variables#default-values), and follows the agent's `on_missing` setting when there is none.
 
 ```text System prompt
 You are the support line for Acme. The caller is {{customer_name}} on the {{plan}} plan
@@ -366,18 +366,18 @@
 
 ### Failure behavior
 
-The endpoint can personalize a call but never block one. The caller is waiting while the request runs, so keep the handler fast and the timeout short.
+The endpoint can personalize a call but never block one. The caller is waiting while the request runs, so keep the handler fast and the timeout short. Whenever the call connects without your variables, every placeholder falls back to its configured [default value](/agents/build/dynamic-variables#default-values), so give each one a default that reads well on its own.
 
 | Outcome                                  | Effect                                                        |
 | ---------------------------------------- | ------------------------------------------------------------- |
 | Response within the timeout              | Variables are rendered into the prompt, first message, and webhook tool requests |
-| Timeout                                  | The call connects without variables; the request is not retried |
-| Connection error or non-`2xx` response   | One immediate retry, then the call connects without variables |
-| Body is not a JSON object                | The call connects without variables                           |
+| Timeout                                  | The call connects on the defaults; the request is not retried |
+| Connection error or non-`2xx` response   | One immediate retry, then the call connects on the defaults   |
+| Body is not a JSON object                | The call connects on the defaults                             |
 
 ## Auto-ticket unresolved calls
 
 `call.analyzed` closes the loop on conversations the agent couldn't: judge every call with a success criterion, and open a ticket in your helpdesk whenever the verdict isn't `success`.
 
 First give the agent's [analysis configuration](/agents/monitor/post-call-analysis) a criterion that captures resolution:
 
@@ -498,11 +498,11 @@
 
 </CodeGroup>
 
 `verifyWebhook` is the function from [Verify the signature](#verify-the-signature); `openTicket` stands in for your helpdesk's API. Escalating on anything but `success` includes `unknown` verdicts: the model couldn't judge the call, which usually deserves human eyes too. Tighten the check to `failure` only if unknowns prove noisy.
 
 Edges worth handling:
 
 - Calls with nothing to analyze arrive with `analysis.status: "skipped"`. The handler above tickets them as unjudged, so every call reaches the helpdesk without also watching `call.ended`. Drop that branch if silent calls don't belong in your queue.
 - Payloads carry no transcript. To include one in the ticket, fetch `GET /v1/agent/sessions/{session_id}` from your handler. See [conversation history](/agents/monitor/conversation-history).
 - Set `end_user_id` and `metadata` when creating sessions so tickets attach to the right customer record without a lookup.
 

agents/telephony/inbound-calls.mdx

@@ -98,8 +98,8 @@
       "metadata": {}
     }
   ],
   "has_more": false,
   "next_cursor": null
 }
 ```
 
@@ -119,7 +119,7 @@
 Hi {{customer_name}}, thanks for calling Acme. Are you calling about order {{last_order}}?
 ```
 
-Set it on the agent's **Webhooks** page in the console (**Inbound call webhook**) or through `webhooks.conversation_init` in the config API, then publish. A slow or failing endpoint never blocks the call: after the configured timeout (up to 8 seconds, default 5) the call connects without variables.
+Set it on the agent's **Webhooks** page in the console (**Inbound call webhook**) or through `webhooks.conversation_init` in the config API, then publish. A slow or failing endpoint never blocks the call: after the configured timeout (up to 8 seconds, default 5) the call connects and every placeholder takes its configured [default value](/agents/build/dynamic-variables#default-values) (`Hi there, thanks for calling Acme.`). Set a default for each placeholder the first message depends on, or set the agent's `on_missing` to `reject` if the call must not connect without them.
 
 ## Phone sessions behave like any session
 

api-reference/openapi.json

@@ -3724,6 +3724,9 @@
                     "llm": {
                       "$ref": "#/components/schemas/AgentLLMConfigRedacted"
                     },
+                    "variables": {
+                      "$ref": "#/components/schemas/AgentVariablesConfig"
+                    },
                     "updated_at": {
                       "format": "date-time",
                       "title": "Updated At",
@@ -3944,6 +3947,9 @@
                     "llm": {
                       "$ref": "#/components/schemas/AgentLLMConfigRedacted"
                     },
+                    "variables": {
+                      "$ref": "#/components/schemas/AgentVariablesConfig"
+                    },
                     "updated_at": {
                       "format": "date-time",
                       "title": "Updated At",
@@ -19492,6 +19498,12 @@
             "title": "Warm Confirm Timeout Seconds",
             "type": "integer"
           },
+          "warm_human_detection": {
+            "default": false,
+            "description": "Applies to warm transfers whose warm_connect is `confirm` or `briefing`, and is ignored for cold transfers and `direct`. When true, once the destination answers, the agent stays silent until the other side speaks, then classifies the pickup. A person is briefed as usual. Voicemail or an IVR (phone menu) ends the transfer as failed. A hold queue or silence keeps the agent waiting until `warm_confirm_timeout_seconds` ends the attempt as unreachable. A failed transfer follows `on_failure`. Leave it off for destinations whose people are only reachable through a phone menu, because the menu stops the transfer.",
+            "title": "Warm Human Detection",
+            "type": "boolean"
+          },
           "on_failure": {
             "$ref": "#/components/schemas/AgentTransferOnFailurePatch"
           },
@@ -19914,6 +19926,18 @@
               }
             ],
             "default": null
+          },
+          "variables": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/PublicAgentVariablesPatch"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Default values for the {{placeholders}} in the configured text, used when the session supplies none (the map replaces as a whole), and on_missing for a placeholder with neither: keep leaves it as written (default), empty renders it as empty text, reject refuses the session."
           }
         },
         "title": "PublicAgentConfigPatchPayload",
@@ -20434,6 +20458,58 @@
         "title": "PublicAgentToolsPatch",
         "type": "object"
       },
+      "PublicAgentVariablesPatch": {
+        "additionalProperties": false,
+        "properties": {
+          "defaults": {
+            "anyOf": [
+              {
+                "additionalProperties": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "integer"
+                    },
+                    {
+                      "type": "number"
+                    },
+                    {
+                      "type": "boolean"
+                    }
+                  ]
+                },
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "title": "Defaults"
+          },
+          "on_missing": {
+            "anyOf": [
+              {
+                "enum": [
+                  "keep",
+                  "empty",
+                  "reject"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "title": "On Missing"
+          }
+        },
+        "title": "PublicAgentVariablesPatch",
+        "type": "object"
+      },
       "PublicAgentVoicePatch": {
         "additionalProperties": false,
         "properties": {
@@ -21414,6 +21490,12 @@
             "title": "Warm Confirm Timeout Seconds",
             "type": "integer"
           },
+          "warm_human_detection": {
+            "default": false,
+            "description": "Applies to warm transfers whose warm_connect is `confirm` or `briefing`, and is ignored for cold transfers and `direct`. When true, once the destination answers, the agent stays silent until the other side speaks, then classifies the pickup. A person is briefed as usual. Voicemail or an IVR (phone menu) ends the transfer as failed. A hold queue or silence keeps the agent waiting until `warm_confirm_timeout_seconds` ends the attempt as unreachable. A failed transfer follows `on_failure`. Leave it off for destinations whose people are only reachable through a phone menu, because the menu stops the transfer.",
+            "title": "Warm Human Detection",
+            "type": "boolean"
+          },
           "on_failure": {
             "$ref": "#/components/schemas/AgentTransferOnFailure"
           },
@@ -21456,6 +21538,43 @@
         "title": "AgentTransferOnFailure",
         "type": "object"
       },
+      "AgentVariablesConfig": {
+        "description": "Defaults for `{{name}}` placeholders and what a placeholder without a value does.",
+        "properties": {
+          "defaults": {
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "boolean"
+                }
+              ]
+            },
+            "title": "Defaults",
+            "type": "object"
+          },
+          "on_missing": {
+            "default": "keep",
+            "enum": [
+              "keep",
+              "empty",
+              "reject"
+            ],
+            "title": "On Missing",
+            "type": "string"
+          }
+        },
+        "title": "AgentVariablesConfig",
+        "type": "object"
+      },
       "AgentVoiceConfigView": {
         "description": "Read shape of the voice section. The ASR fields that moved to the asr\nsection stay mirrored here, deprecated, so clients written before the split\nkeep reading them.",
         "properties": {
@@ -21741,6 +21860,9 @@
           "llm": {
             "$ref": "#/components/schemas/AgentLLMConfigRedacted"
           },
+          "variables": {
+            "$ref": "#/components/schemas/AgentVariablesConfig"
+          },
           "updated_at": {
             "format": "date-time",
             "title": "Updated At",