Skip to content

Commit da269f6

Browse files
dhruva-reddydhruva-reddy
authored
docs: enrich dynamic-variables table and document function.parameters tool support (#1037)
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 8d316d4 commit da269f6

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)