Millis AI allows you to attach metadata to your call sessions when using the Web SDK or starting outbound calls. Metadata can include any user-specific data, such as the caller’s name, user ID, or other relevant information. The system provides multiple ways to utilize this metadata during the session.

​
How to Add Metadata

​
1. Via URL Parameters (Embedded Widget)

When using the embeddable call widget, you can add metadata directly through URL parameters:

https://app.millis.ai/agents/embedded?id=XXXX&k=YYYYYY&userName=John&userType=premium

Any query parameters added to the widget URL will automatically become metadata for that session.

​
2. Using the Web SDK

You can add metadata to a call using the Web SDK by providing the metadata as the second parameter in the start method. The third parameter, include_metadata_in_prompt, determines whether the metadata should be included in the agent’s system prompt.

msClient.start(<agent-id>, metadata?: object, include_metadata_in_prompt?: boolean);
  • The first parameter is the agentId or a temporary agent configuration.
  • The second parameter is the metadata you want to attach to the session.
  • The third parameter is include_metadata_in_prompt, which controls whether the metadata is used by the agent during the conversation.

Learn more about our Web SDK here.

​
3. Using the native Websocket connection

You can also attach metadata by initiating a session through a WebSocket connection. Include the metadata in the initiate method payload.

{
  "method": "initiate",
  "data": {
    "agent": {
      "agent_id": "your_agent_id",
      Or replace with agent_config: <config> for dynamic configuration
    },
    "public_key": "your_public_key",
    "metadata": {
      "key": "value"
    },
    "include_metadata_in_prompt": true
  }
}

Learn more about building native apps using websocket here.

​
4. Using the Outbound API

To add metadata using the outbound API, you need to include it in the request body when calling the start_outbound_call API. You can also specify whether to include the metadata in the agent’s prompt.

{
  "from_phone": "one of your agent's phone number",
  "to_phone": "receiver's phone number",
  "metadata": {
    "key": "value"
  },
  "include_metadata_in_prompt": true
}
  • from_phone: One of your agent’s phone numbers.
  • to_phone: The phone number of the call recipient.
  • metadata: Optional. Any extra data you want to attach to the session.
  • include_metadata_in_prompt: Optional. Set to true to include metadata in the agent’s prompt. Defaults to false.

Learn more about Outbound Call here.

​
How to retrieve and use Metadata

The metadata will stay associated with that session throughout its lifecycle. This metadata will also be included in the following:

  • Prefetch Data Webhook: Metadata is forwarded during the session’s prefetch data webhook which you can use to retrieve personalized data.
  • End of Call Webhook: Metadata is passed along at the conclusion of the call, allowing you to track and identify sessions.

Learn more about the webhooks here.

​
Use Metadata as Variables

Any metadata you attach to a call session can be used as dynamic variables throughout your call flow. Variables can be referenced in agent prompts, messages, webhook parameters, and function calls using the {variableName} syntax.

For example, if you add metadata like:

{
  "userName": "John",
  "userType": "premium"
}

You can reference these values using {userName} or {userType} in various places during the call.

For detailed information about using variables, including syntax and examples, see our Variables documentation.

WebhooksDynamic Variables