Chat Custom Data

Custom Data lets you pass information from your website into Octocom conversations. By writing values to localStorage with a specific prefix, the chat widget automatically picks them up and attaches them to the conversation as metadata.

This is useful when your website knows something about the visitor — their user ID, subscription tier, the page they're on, or anything else — and you want the bot or your team to have that context.

How it works

1. Your website writes key-value pairs to localStorage using the octocom:data: prefix.
2. When the visitor starts a conversation or sends a message, the chat widget reads all matching keys and sends them to the backend.
3. Each key-value pair is stored as conversation metadata with a chat-widget: prefix — for example, octocom:data:user_id becomes metadata key chat-widget:user_id.
4. The metadata is visible in the dashboard, accessible in custom Python actions, and available for analytics queries.

Values are synced on every message. If a value is added to localStorage mid-conversation (e.g., after the customer logs in), it will be picked up on the next message they send.

Setting custom data

Add values to localStorage anywhere in your frontend code. The chat widget handles the rest.

// Set a single value
localStorage.setItem("octocom:data:user_id", "12345");

// Set multiple values
localStorage.setItem("octocom:data:plan", "enterprise");
localStorage.setItem("octocom:data:company", "Acme Corp");

To remove a value:

localStorage.removeItem("octocom:data:user_id");

Removing a key from localStorage does not delete the metadata already stored on the conversation. It simply stops sending that key on future messages.

Special keys

Three keys receive special treatment. When present, they automatically update the customer record associated with the conversation — the same customer record visible in the dashboard sidebar.

These values are stored both as conversation metadata and on the customer object. This means they're available everywhere: in the dashboard, in custom actions, and in analytics.

// After the user logs in on your site
const user = getCurrentUser();
localStorage.setItem("octocom:data:email", user.email);
localStorage.setItem("octocom:data:name", user.fullName);

Use cases

Custom data is flexible by design. Here are some examples of what you can do with it.

Identify logged-in users

Pass the user's ID so custom actions can fetch their account details without asking.

localStorage.setItem("octocom:data:user_id", user.id);

Provide customer context to the bot

Include the customer's subscription plan, account status, or loyalty tier so the bot can tailor its responses.

localStorage.setItem("octocom:data:plan", "premium");
localStorage.setItem("octocom:data:account_status", "active");
localStorage.setItem("octocom:data:loyalty_tier", "gold");

Share purchase history

Serialize recent orders as JSON so a custom action can parse and use them.

const recentOrders = JSON.stringify([
  { id: "ORD-001", total: 59.99, date: "2025-03-15" },
  { id: "ORD-002", total: 124.5, date: "2025-03-28" },
]);
localStorage.setItem("octocom:data:recent_orders", recentOrders);

Track the customer's current page or product

Let the bot know what the customer is looking at right now.

localStorage.setItem("octocom:data:current_product", "wireless-headphones-pro");
localStorage.setItem("octocom:data:current_category", "electronics");

Pass locale and currency preferences

Ensure the bot responds in the right context when your site supports multiple regions.

localStorage.setItem("octocom:data:locale", "fr-FR");
localStorage.setItem("octocom:data:currency", "EUR");

Include cart value for prioritization

High-value carts might warrant faster handoff to a human agent.

localStorage.setItem("octocom:data:cart_value", "489.99");
localStorage.setItem("octocom:data:cart_items_count", "7");

Share referral or campaign source

Track which marketing campaign brought the visitor to chat.

const params = new URLSearchParams(window.location.search);
const utm_source = params.get("utm_source");
if (utm_source) {
  localStorage.setItem("octocom:data:utm_source", utm_source);
}

Indicate feature flags or A/B test variants

Let the bot know which experiment group the visitor belongs to.

localStorage.setItem("octocom:data:experiment", "checkout-v2");

Provide support context

If the user navigated to chat from a specific help article or error page, pass that context along.

localStorage.setItem("octocom:data:help_article", "returns-policy");
localStorage.setItem("octocom:data:error_code", "PAYMENT_DECLINED_3042");

Pass device or app version

For SaaS products, include the app version or environment so support knows what the customer is running.

localStorage.setItem("octocom:data:app_version", "2.14.3");
localStorage.setItem("octocom:data:environment", "production");

Share warehouse or store location

For businesses with multiple locations, indicate which one the customer is associated with.

localStorage.setItem("octocom:data:store_id", "store-chicago-downtown");
localStorage.setItem("octocom:data:warehouse", "us-east-1");

Include booking or reservation details

Pass upcoming reservation info so the bot can help with modifications.

localStorage.setItem("octocom:data:reservation_id", "RES-88421");
localStorage.setItem("octocom:data:check_in", "2025-04-15");

Using custom data in Python actions

Custom data stored as conversation metadata can be read by custom Python actions using the get_conversation_metadata helper. This lets your actions pull in context without requiring the bot to pass it as an argument.

Example: Fetch account details using a logged-in user's ID

This action reads the user ID from metadata, calls an external API, and returns the account information to the bot.

import requests

def execute_action(context):
    user_id = get_conversation_metadata(context, "chat-widget:user_id")
    if not user_id:
        return {
            "error": "No user ID found. The customer may not be logged in."
        }

    response = requests.get(
        "https://api.yoursite.com/users",
        params={"id": user_id},
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

The bot receives the returned data and can use it to answer the customer's questions — for example, looking up their order status, subscription details, or account settings.

Example: Return the customer's purchase history from metadata

If your website serializes purchase history into localStorage, a Python action can parse it directly — no external API call needed.

import json

def execute_action(context):
    raw = get_conversation_metadata(context, "chat-widget:recent_orders")
    if not raw:
        return {"error": "No purchase history available."}

    orders = json.loads(raw)
    return {"orders": orders, "total_orders": len(orders)}

The bot can then reference specific orders, total spend, or recent purchase dates when helping the customer.

Using custom data for analytics

All custom data is stored as conversation metadata and can be queried in the Octocom dashboard or via the API. This opens up several analytics possibilities:

• Filter conversations by metadata values — for example, find all conversations from customers on the enterprise plan.
• Segment by source — compare conversations from different UTM campaigns or referral sources.
• Aggregate by store or region — break down conversation volume by store_id or locale.
• Correlate cart value with outcomes — analyze whether high-value cart conversations are more likely to result in handoffs or purchases.

Metadata keys are visible in the Metadata section of the conversation details sidebar in the dashboard.

Testing

You can test custom data without deploying any code changes.

Using Chrome DevTools

1. Open your website (or the Octocom playground) in Chrome.
2. Open DevTools (F12 or Cmd+Option+I).
3. Go to the Console tab.
4. Set your test values:

localStorage.setItem("octocom:data:user_id", "test-123");
localStorage.setItem("octocom:data:email", "[email protected]");

5. Start a new conversation in the chat widget.
6. Open the conversation in the Octocom dashboard — you should see the metadata in the Metadata section of the sidebar, and the customer email should be set.

Custom data is read when a message is sent. If you set localStorage values after the conversation has started, send another message to trigger the sync.

Verifying in the dashboard

In the conversation details sidebar, look for:

• Metadata section — should show entries like chat-widget:user_id: test-123
• Customer section — should show the email if you set the email special key

Technical notes

• Key format: Only keys with the exact prefix octocom:data: are read. The prefix is stripped, and the remainder becomes the metadata key with a chat-widget: prefix.
• Value type: All values are stored as strings. If you need structured data (arrays, objects), serialize it as JSON.
• Size limits: Metadata keys can be up to 200 characters, values up to 50,000 characters. Each conversation supports up to 200 metadata pairs.
• Persistence: Metadata is stored on the conversation permanently. Removing a key from localStorage does not remove existing metadata — it only stops sending that key on future messages.
• Upsert behavior: If the same key is sent again with a different value, the metadata is updated to the new value.
• No authentication required: The chat widget handles transmission automatically. No API keys or additional setup is needed beyond setting localStorage values.