feat: Add auto-fill for missing dynamic variables

[edu-ap]

Problem

When an ElevenLabs agent has tools configured with dynamic variable references, the server validates that all referenced dynamic variables are provided during conversation initiation. If any are missing, the conversation fails with an error like:

"This conversation failed with the following reason: Missing required dynamic variables in tools: {'previous_clients', 'clients', 'previous_matters', 'conversation_history', 'previous_submissions', 'matters'}"

This creates problems when:

• Different parts of your application provide different sets of dynamic variables
• Team members add new dynamic variables to agent tools without coordination
• You don't always have values for all required dynamic variables
• Frontend developers don't have visibility into which variables the agent expects

Solution

This PR adds auto-fill functionality for missing dynamic variables. Developers can now:

1. Specify which dynamic variables their agent expects
2. Define a default value for any missing variables
3. Avoid conversation failures due to missing variables

Changes

New Configuration Options

expectedDynamicVariables?: string[]

List of all dynamic variable names that your agent's tools expect.

missingDynamicVariableDefault?: string | number | boolean | null

Default value to use for any missing variables (defaults to null).

Usage Example

Before (would fail):

conversation.startSession({
  agentId: 'your-agent-id',
  dynamicVariables: {
    clients: 'Client A',
    matters: 'Matter B',
  },
});
// ❌ Error: Missing required dynamic variables

After (works!):

conversation.startSession({
  agentId: 'your-agent-id',
  dynamicVariables: {
    clients: 'Client A',
    matters: 'Matter B',
  },
  expectedDynamicVariables: [
    'clients',
    'matters',
    'previous_clients',
    'previous_matters',
    'conversation_history',
    'previous_submissions',
  ],
  missingDynamicVariableDefault: null,
});
// ✅ Success! Missing variables automatically filled with null

Web Widget Example

<elevenlabs-convai-widget
  agent-id="your-agent-id"
  dynamic-variables='{"clients":"Client A","matters":"Matter B"}'
  expected-dynamic-variables='["clients","matters","previous_clients","previous_matters"]'
  missing-dynamic-variable-default="null"
></elevenlabs-convai-widget>

Benefits

✅ Prevents conversation failures due to missing dynamic variables
✅ Backward compatible - existing code works without changes
✅ Works across all SDKs - client, react, react-native, and widget
✅ Flexible defaults - supports null, strings, numbers, and booleans
✅ Developer-friendly - clear documentation and TypeScript types
✅ Decouples frontend from backend - frontend doesn't need to know all agent variables upfront

Files Changed

Client SDK

• packages/client/src/utils/BaseConnection.ts - Added type definitions
• packages/client/src/utils/overrides.ts - Implemented auto-fill logic

React Native SDK

• packages/react-native/src/types.ts - Added type definitions
• packages/react-native/src/utils/overrides.ts - Implemented auto-fill logic
• packages/react-native/src/hooks/useConversationSession.ts - State management
• packages/react-native/src/ElevenLabsProvider.tsx - Integration

Widget SDK

• packages/convai-widget-core/src/types/attributes.ts - Added HTML attributes
• packages/convai-widget-core/src/contexts/session-config.tsx - Attribute parsing

Documentation

• DYNAMIC_VARIABLES_GUIDE.md - Comprehensive usage guide

Testing

• ✅ TypeScript compilation passes
• ✅ Build succeeds for all packages
• ✅ Type safety verified
• ✅ Backward compatibility maintained
• ✅ All linting checks pass

Documentation

Comprehensive guide added at DYNAMIC_VARIABLES_GUIDE.md with:

• Detailed explanations
• Examples for all SDKs (React, React Native, Widget, vanilla JS)
• Best practices
• Migration guide

[PaulAsjes]

Thanks for the contribution! Could the explanation on how to use this be put in each package's respective README file instead please?

[PaulAsjes]

Please undo the changes to this file, we don't want to add dependencies or reorder them.

[edu-ap]

Thank you very much for the review @PaulAsjes! I have addressed both of your feedback points:

1. ✅ Moved the documentation from the root guide to each package's README:

   • Added to packages/client/README.md
   • Added to packages/react/README.md
   • Added to packages/react-native/README.md
   • Added to main README.md (for widgets)

2. ✅ Reverted all changes to package.json and pnpm-lock.yaml

I also removed package-lock.json that was accidentally added and updated .gitignore to prevent it in the future.

The PR should be ready for re-review now. Let me know if there's anything else you'd like me to adjust!

[PaulAsjes]

Thanks for the effort put in here!

Spoke with the team about this and we've decided to not merge this PR. The idea that all dynamic variables should be defined before a conversation can start was made a long time ago, way before users had the ability to update variables mid-call (e.g. tool assignments). We might revisit that decision in the future as the frustration you encounter is valid.

That being said, this needs to be resolved properly on the server side rather than the client. I don't think this PR fixes the described issue of

so that a small change in agent config in the ElevenLabs UI does not break the Web experience for all the users

because it still relies on listing all dynamic variables that are used, directly in the client. If the agent configuration is changed to introduce a new dynamic variable, it will still break existing clients.

We're tracking this issue internally and will look into properly fixing it on the server.

[edu-ap]

Thank you very much @PaulAsjes, if you have any news of this changing in the future please let me know.