Attach session metadata

Session metadata attaches key-value pairs to posts created through the widget, so your team can see which page a user was on, which app version they ran, or which plan they are on, without asking. This article shows how to set, update, and remove metadata.

Set metadata

Call metadata with a plain object of key-value pairs:

Quackback("metadata", {
  page: "/settings/billing",
  app_version: "2.4.1",
  plan: "pro",
});

With the npm package, use Quackback.metadata({ ... }).

Metadata is merged on each call, so you can update one key without clearing the rest:

// Initial metadata
Quackback("metadata", { page: "/dashboard", plan: "pro" });

// The user navigates: only page changes
Quackback("metadata", { page: "/settings" });
// Result: { page: "/settings", plan: "pro" }

To remove a key, set it to null:

Quackback("metadata", { page: null });
// Result: { plan: "pro" }

All values are stored as strings. Other values are converted with String().

Note: You can set metadata before the widget has loaded. It is queued and sent once the widget is ready.

Where metadata is stored

When a user submits a post through the widget, the current metadata is saved with that post (as JSON in the post's widget_metadata field in the database). Metadata applies to feedback posts, not to Messenger conversations.

Single-page apps

Update metadata on route changes so each post records the page it came from:

import { useEffect } from "react";
import { useLocation } from "react-router-dom";
import { useAuth } from "@/hooks/use-auth";

export function WidgetMetadata() {
  const location = useLocation();
  const { user } = useAuth();

  useEffect(() => {
    Quackback("metadata", {
      page: location.pathname,
      app_version: import.meta.env.VITE_APP_VERSION,
    });
  }, [location.pathname]);

  useEffect(() => {
    if (user) {
      Quackback("metadata", { plan: user.plan, company: user.company });
    }
  }, [user]);

  return null;
}

Tip: Keep keys short and consistent, for example snake_case. Do not store passwords, tokens, or personal data beyond what your team needs for context. For user properties you want to filter and segment on, use custom attributes in the identify token instead.

Related articles

• Listen to widget events
• Install the widget
• Identify users