Attach metadata to call

Attach metadata to your call sessions for personalized conversations

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.