Chat Custom Data

Custom Data lets you pass information from your website into Octocom conversations. By writing values to localStorage with a specific prefix — or by adding prefixed query parameters to the page URL — 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

Your website writes key-value pairs to localStorage using the octocom:data: prefix (or the visitor lands on a URL with octocom_data_ query parameters, which the widget saves to those same keys).
When the visitor starts a conversation or sends a message, the chat widget reads all matching keys and sends them to the backend.
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.
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.

Setting custom data via URL query parameters

You can also pass custom data in the page URL — no code changes on your site required. Any query parameter whose name starts with octocom_data_ is captured when the chat widget loads:

https://yoursite.com/landing?octocom_data_utm_source=google&octocom_data_campaign=spring-sale

The example above sets the custom data keys utm_source and campaign, which become conversation metadata chat-widget:utm_source and chat-widget:campaign.

This is ideal for links you control — marketing campaigns, emails, QR codes, or support links — where you want the resulting chat conversations tagged with the link's context.

How it behaves:

Query parameters are read once per page load, when the widget script runs, and held in memory. They are saved to localStorage under the corresponding octocom:data: key when the visitor opens the chat — the widget writes nothing to the browser before that (see Browser Storage & Consent).
Once saved, the data survives navigation: the visitor can browse to other pages and the data stays attached to their conversations.
If the visitor navigates to another page without ever opening the chat, parameters captured from the previous URL are not retained. Keep the parameters in the destination URL, or write the octocom:data: keys from your own site code, if you need them to persist regardless.
If a key already exists in localStorage, the query parameter value overwrites it.
The special keys work here too — e.g. [email protected] sets the customer's email.
Values must be URL-encoded (e.g. spaces as %20).

https://yoursite.com/help?octocom_data_error_code=PAYMENT_DECLINED_3042
https://yoursite.com/support?octocom_data_plan=enterprise&octocom_data_company=Acme%20Corp

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.

localStorage key	Effect
`octocom:data:email`	Sets the customer's email address
`octocom:data:name`	Sets the customer's display name
`octocom:data:phone`	Sets the customer's phone number

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.

Privacy note: custom data is your data, passed under your responsibility as the data controller — especially when it identifies a person (email, name, user ID). Pass what the bot genuinely needs, and reflect the practice in your own privacy policy. See Browser Storage & Consent.

// 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");

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");

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");

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

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

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

Start a new conversation in the chat widget.
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.

To test the query parameter approach, simply open any page that has the widget installed with test parameters appended, then start a conversation:

https://yoursite.com/?octocom_data_user_id=test-123

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 localStorage keys with the exact prefix octocom:data: (or query parameters with the 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 for as long as the conversation is retained (see Data Handling & GDPR). 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.

Chat Custom Data

On this page