You can pass a JSON object that maps variable names to values at conversation start, but each dynamic variable’s value must be a scalar (string, number, boolean). Nested/structured JSON cannot be stored as a single dynamic variable. (elevenlabs.io)
Best practice for feeding context at initiation
Prefer Dynamic Variables over Overrides. Template your system prompt/first message with {{variable_name}} and pass values via conversation_initiation_client_data.dynamic_variables when starting the session. Use Overrides only when you need to fully replace the prompt/first message or settings. (elevenlabs.io)
How to pass them:
SDK/server: include dynamic_variables in ConversationInitiationData. (elevenlabs.io)
Public talk-to page: include variables via base64-encoded JSON in the vars URL param, or as var_ query params. (elevenlabs.io)
Web widget: set the dynamic-variables attribute with a JSON object (values still must be scalars). (elevenlabs.io)
Inbound Twilio: return conversation_initiation_client_data (with dynamic_variables and optional overrides) from your webhook. (elevenlabs.io)
Keep sensitive values out of prompts: use secret dynamic variables by prefixing with secret__ so they’re only used in headers and never sent to the LLM. (elevenlabs.io)
If you have structured JSON you want the agent to use, fetch it via a tool/webhook and map the needed fields into dynamic variables (tools can update variables based on JSON responses using dot-path assignments). (elevenlabs.io)
Reference details
Supported dynamic variable types: string, number, boolean; system__ variables are reserved and cannot be client-set. (elevenlabs.io)
for conversation initiation webhooks, can I return structured variables like arrays or objects within the dynamic_variables object?
For example:
{
"type": "conversation_initiation_client_data",
"dynamic_variables": {
"arr": [{...}, {...}]
}
}
pure yarrow
woven musk