Skip to content

Commit 085efad

Browse files
dhruva-reddydhruva-reddy
committed
docs: enrich dynamic-variables table and document function.parameters tool support
Two related additions surfaced by an FDE conversation about progressive authentication, where customers asked which Liquid variables are available and which tools support customer-defined function.parameters. fern/assistants/dynamic-variables.mdx: - Add 5 new rows to the Default Variables table: - phoneNumber.number (the Vapi number that received/placed the call) - phoneNumber.name (display name set on the number) - call.id (Vapi-generated call UUID — useful for log correlation) - call.type (inboundPhoneCall / outboundPhoneCall / webCall) - transport.callSid (provider-side CallSid, useful for BYOT) - Tweak the {{now}} description to point at the Advanced date and time usage section for non-UTC timezones (the LiquidJS "now" | date filter is the only correct pattern; the bag's {{now}} is hardcoded UTC). - Add a callout linking to /tools/static-variables-and-aliases for the trust-tier framing and the within-assistant tool-chaining pattern. fern/tools/custom-tools.mdx: - Add a new section 'Other tool types that accept custom function parameters' with a matrix showing where customer-defined function.parameters works (function, apiRequest, code, handoff) vs. where the schema is Vapi-controlled (transferCall, endCall, dtmf, voicemail, sms, slack, GHL/Google integrations, mcp, make, and the Anthropic-native bash/computer/textEditor tools). - Includes a follow-on pointer to /tools/static-variables-and-aliases for the static-parameters pattern. Variables intentionally NOT exposed (judgment call): - phoneNumber.id, phoneNumber.provider — internal IDs / infra fingerprints; no clear customer use case in prompts. - call.status, call.startedAt, call.assistantId — internal state that is confusing if surfaced in customer prompts. - assistant.id, assistant.name — encourages brittle customer code that hardcodes behavior on assistant identity. - currentDateTime — redundant with {{now}}. - transport.provider — internal-infra fingerprint.
1 parent ecee462 commit 085efad

2 files changed

Lines changed: 35 additions & 12 deletions

File tree

‎fern/assistants/dynamic-variables.mdx‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -69,18 +69,27 @@ For example, set the assistant's first message to "Hello, `{{name}}`!" and assig
6969

7070
These variables are automatically filled based on the current (UTC) time, so you don't need to set them manually in `variableValues`:
7171

72-
| Variable | Description | Example |
73-
| ----------------------- | --------------------------------- | ------------------------- |
74-
| `{{now}}` | Current date and time (UTC) | Jan 1, 2024 12:00 PM |
75-
| `{{date}}` | Current date (UTC) | Jan 1, 2024 |
76-
| `{{time}}` | Current time (UTC) | 12:00 PM |
77-
| `{{month}}` | Current month (UTC) | January |
78-
| `{{day}}` | Current day of month (UTC) | 1 |
79-
| `{{year}}` | Current year (UTC) | 2024 |
80-
| `{{customer.number}}` | Customer's phone number | +1xxxxxxxxxx |
81-
| `{{customer.X}}` | Any other customer property | |
82-
| `{{transport.conversationType}}` | Whether the conversation is over `chat` or `voice` | `chat` |
83-
| `{{transport.X}}` | Any other transport-related property | |
72+
| Variable | Description | Example |
73+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
74+
| `{{now}}` | Current date and time (UTC). For other timezones, use the LiquidJS `date` filter -- see [Advanced date and time usage](#advanced-date-and-time-usage) below. | Jan 1, 2024 12:00 PM |
75+
| `{{date}}` | Current date (UTC) | Jan 1, 2024 |
76+
| `{{time}}` | Current time (UTC) | 12:00 PM |
77+
| `{{month}}` | Current month (UTC) | January |
78+
| `{{day}}` | Current day of month (UTC) | 1 |
79+
| `{{year}}` | Current year (UTC) | 2024 |
80+
| `{{customer.number}}` | The customer's phone number (caller-ID for inbound calls, destination for outbound calls). | +1xxxxxxxxxx |
81+
| `{{customer.X}}` | Any other customer property you set when creating the call. | |
82+
| `{{phoneNumber.number}}` | The Vapi phone number that received the inbound call or placed the outbound call. | +1xxxxxxxxxx |
83+
| `{{phoneNumber.name}}` | The display name you set on this phone number in the dashboard. | `Main Support Line` |
84+
| `{{call.id}}` | The unique Vapi-generated ID for this call. Useful for correlating with your own logs, support tickets, or webhooks. | `5fe26c8e-...` |
85+
| `{{call.type}}` | The kind of call this is. Useful for branching prompt behavior between channels. | `inboundPhoneCall` / `outboundPhoneCall` / `webCall` |
86+
| `{{transport.callSid}}` | The provider-side call session ID (e.g. Twilio's `CallSid`). Useful for BYOT customers correlating with their own provider logs. | `CA1234...` |
87+
| `{{transport.conversationType}}` | Whether the conversation is over `chat` or `voice`. | `chat` |
88+
| `{{transport.X}}` | Any other transport-related property. | |
89+
90+
<Note>
91+
To pass these values **between tool calls within an assistant** (rather than templating them into prompts), see [Static variables and aliases](/tools/static-variables-and-aliases). That page documents the trust tiers for these variables -- which are signaling-derived and safe to use as a security boundary in tool calls, vs. conversation-derived ones that are not -- and shows how to inject them into tool calls deterministically, without LLM mediation.
92+
</Note>
8493

8594
## Advanced date and time usage
8695

‎fern/tools/custom-tools.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,20 @@ vapi listen --forward-to localhost:3000/tools/webhook
119119
`vapi listen` is a local forwarder that requires a separate tunneling service. Configure your tool's server URL to use the tunnel's public URL for testing. [Learn more →](/cli/webhook)
120120
</Note>
121121

122+
## Other tool types that accept custom function parameters
123+
124+
Custom function tools are not the only tool type where you can define an LLM-facing JSON schema. Several other tool types accept the same `function.parameters` customization, so the dashboard's **Parameters** editor (or the `function` field in the API) works the same way across them.
125+
126+
| Tool type | Customer-defined `function.parameters`? |
127+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
128+
| `function` (custom) | Yes — the entire purpose of this tool type. |
129+
| `apiRequest` | Yes — drives both the LLM-supplied arguments and the request body construction. |
130+
| `code` | Yes — the parameters become inputs to your TypeScript code. |
131+
| `handoff` | Yes — fills handoff-time arguments inline. See [Approach 1 in the squads guide](/squads/passing-data-between-assistants#approach-1-handoff-arguments). |
132+
| `transferCall`, `endCall`, `dtmf`, `voicemail`, `sms`, `slack-send-message`, GHL/Google integrations, `mcp`, `make`, Anthropic-native (`bash`, `computer`, `textEditor`) | No — the schema is Vapi-controlled or auto-derived from the underlying integration; you do not define it directly. |
133+
134+
For tool types that accept customer-defined `function.parameters`, you can also pair them with **static parameters** -- a separate top-level `parameters` array on the tool that merges server-trusted values into the body without the LLM ever seeing them. See [Static variables and aliases](/tools/static-variables-and-aliases) for the full pattern, including when to use static parameters as a security boundary.
135+
122136
## Alternative: API Configuration
123137

124138
For advanced users who prefer programmatic control, you can also create and manage tools via the Vapi API:

0 commit comments

Comments
 (0)