Chat Metadata Pass-Through

Pass arbitrary context alongside chat messages to any AI Agent so it can tailor responses to the user's exact situation.

---

Overview

The chat metadata feature lets you pass arbitrary context alongside chat messages to any IBL Agent. This context (e.g., product name, plan tier, user role) is automatically injected into the agent's awareness, allowing it to tailor responses to the user's exact situation without the user having to explain their context manually.

Key points:

• The metadata field is a free-form JSON object — any key-value pairs are accepted, no enforced schema
• Optional — if omitted, the agent behaves as before
• Persistent per session — send it once and it sticks for the entire conversation
• Available in analytics — stored with the conversation for reporting and data exports

---

How It Works

Frontend Application
    |
    |  Sends: { prompt, metadata: { product, planTier, ... } }
    |
    v
IBL Agent Backend
    |
    ├─ Caches metadata for the session (reused on subsequent messages)
    ├─ Persists metadata to the session record (for analytics/reporting)
    |
    v
Agent (LLM) receives the user's message with context appended:

    "How do I set up SSO?"

     Here is additional context metadata for this conversation:
    product: Analytics
    planTier: Enterprise
    userRole: Admin
    region: EU
    

The agent sees this context and responds accordingly — e.g., answering with Enterprise-tier SSO setup steps for the Analytics product with EU data-residency considerations, rather than generic help.

---

Sending Metadata

WebSocket (/ws/chat/)

Include the metadata field in the JSON payload:

ws.send(JSON.stringify({
  session_id: sessionId,
  prompt: userMessage,
  page_content: pageContent,       // optional
  metadata: {                       // optional
    product: 'Analytics',
    planTier: 'Enterprise',
    userRole: 'Admin',
    region: 'EU'
  },
  flow: { name: mentorId, tenant: tenantKey }
}));

HTTP SSE (POST /api/agent/chat/)

Same metadata field in the request body:

POST /api/agent/chat/
Content-Type: application/json

{
  "session_id": "uuid",
  "prompt": "How do I set up SSO?",
  "metadata": {
    "product": "Analytics",
    "planTier": "Enterprise",
    "userRole": "Admin",
    "region": "EU"
  },
  "flow": { "name": "agent-slug", "tenant": "tenant-key" }
}

Embedded iframe (postMessage)

If the agent is embedded via iframe, the host page passes metadata through the postMessage channel:

iframe.contentWindow.postMessage({
  type: 'MENTOR:CONTEXT_UPDATE',
  hostInfo: {
    title: document.title,
    href: window.location.href
  },
  pageContent: bodyContent,
  metadata: {
    productGroup: 'LICENSING',
    productLevel: 'LH',
    stateCode: 'CA'
  }
}, '*');

The chat widget should:

1. Listen for postMessage events with type: 'MENTOR:CONTEXT_UPDATE'
2. Extract the metadata object from the message
3. Include it in every WebSocket payload sent to the backend

---

Session Behavior

Metadata is cached per session and only needs to be sent once. Here's how it behaves across multiple messages:

Rules:

• Send once — metadata persists automatically for the rest of the session
• Replace, not merge — sending new metadata replaces the previous value entirely
• Null or omitted = no change — the previously cached metadata continues to be used
• Cache TTL — metadata is cached for 2 hours; it is also persisted to the database so it survives cache expiration

---

Metadata Structure

The metadata field accepts any JSON object. There is no enforced schema — use whatever keys make sense for your application.

Example: SaaS customer support

{
  "product": "Analytics",
  "planTier": "Enterprise",
  "userRole": "Admin",
  "region": "EU"
}

Example: Corporate training platform

{
  "department": "Engineering",
  "courseId": "SEC-201",
  "courseName": "Security Fundamentals",
  "employeeLevel": "Senior"
}

Example: E-commerce product advisor

{
  "category": "Laptops",
  "brand": "ThinkPad",
  "priceRange": "1000-2000",
  "customerSegment": "Business"
}

---

Customizing Agent Behavior with Metadata

The metadata is appended to the user's prompt as context. The agent's system prompt determines how it uses this context. If the agent isn't responding the way you expect based on the metadata, you can edit the system prompt to reference the metadata fields explicitly.

Example system prompt excerpt:

You are a product support assistant. When the user's context includes a
product name, tailor your answers to that specific product's features and
documentation. When planTier is provided, only suggest features available
on that plan. When region is EU, highlight GDPR and data-residency details.

---

Reading Metadata from APIs

Once metadata is sent with a conversation, it's available through several APIs for analytics, reporting, and data exports.

Data Exports

---

Example: Single Agent Serving Multiple Contexts

Scenario: One support agent handles questions across your entire SaaS platform, but users are on different product pages with different plans.

Page: Analytics product — Enterprise plan

The frontend sends:

{
  "metadata": {
    "product": "Analytics",
    "planTier": "Enterprise",
    "userRole": "Admin",
    "region": "EU"
  }
}

User asks: "How do I set up SSO?"

Agent responds with Enterprise-tier SSO setup steps for the Analytics product, noting EU data-residency requirements — not generic help docs.

Page: Payments product — Starter plan

The frontend sends:

{
  "metadata": {
    "product": "Payments",
    "planTier": "Starter",
    "userRole": "Developer",
    "region": "US"
  }
}

Same agent now responds with Starter-plan Payments integration guides, and notes that SSO requires upgrading to the Pro plan.

If the agent's responses don't align with the expected behavior, adjust the system prompt to instruct the agent on how to use the metadata fields.

---

Architecture Reference

Client payload
    |
    v
BaseConsumerPayload (pydantic validation)
    |
    v
BaseLLMRunnerConsumer.process_text_data()
    |
    ├─► Redis Cache: session_{session_id}_metadata  (2-hour TTL, fast access)
    ├─► Session.metadata["client_context"]           (persistent DB storage)
    |
    v
LLMRunner.asetup_user_prompt()
    |
    ├─ 1. Add greeting instructions
    ├─ 2. Append page_content (if provided)
    └─ 3. Append metadata (formatted as key: value pairs)
    |
    v
LLM receives the composed prompt
    |
    v
Response returned to user
    |
    v
Message saved to chat history
(metadata markers remain in saved messages)

Storage layers:

Transport: Both WebSocket (/ws/chat/) and HTTP SSE (POST /api/agent/chat/) share the same pipeline. The metadata field works identically on both.

---

Notes

• The metadata structure is generic — not tied to any specific client's data model. Use whatever keys make sense for your application.
• Metadata is stored at the session level. All messages in a conversation share the same metadata unless the frontend sends an update.
• Metadata is not stripped from chat history (unlike page_content, which is stripped before saving). The markers remain in the stored messages.
• If the agent's behavior doesn't reflect the metadata context as expected, update the agent's system prompt to explicitly reference the metadata fields.