Adding User Context

The SDK automatically tracks the current page. You can optionally pass additional context — user role, feature name, error state, or custom data — so the copilot can tailor responses and filter tool suggestions.

Without extra context, the copilot knows where the user is. With context, it also knows who they are and what's happening — an admin on the billing page experiencing a payment error gets very different help than a new user on the dashboard.

Page tracking is automatic. The SDK detects route changes (pushState, popstate, hash changes) and sets currentPage to the current pathname. Each route change overwrites the previous value. No setup required.

Basic usage

Use setContext to pass additional information beyond the current page.

Important: setContext is an instance method, not a static method. For Vanilla JS, use Pillar.getInstance() to get the SDK instance after initialization.

examples/guides/context/basic-usage.tsx

import { usePillar } from '@pillar-ai/react';

function SettingsPage() {
  const { pillar } = usePillar();

  useEffect(() => {
    pillar?.setContext({
      currentPage: '/settings',
      currentFeature: 'Account Settings',
      userRole: 'admin',
    });
  }, [pillar]);

  return <Settings />;
}

Context Properties

Property	Type	Description
`currentPage`	`string`	Auto-set by the SDK to `window.location.pathname`. You can override it, but the next route change will replace your value.
`currentFeature`	`string`	Human-readable feature name (e.g., `Billing Settings`)
`userRole`	`string`	User's role for tool filtering (e.g., `admin`, `member`)
`userState`	`string`	User's current state (e.g., `onboarding`, `trial`, `active`)
`errorState`	`object`	Current error with `code` and `message`
`custom`	`object`	Any additional context data

Feature-Specific Context

Set context based on what the user is doing:

examples/guides/context/feature-specific-context.tsx

function BillingPage() {
  const { pillar } = usePillar();

  useEffect(() => {
    pillar?.setContext({
      currentPage: '/settings/billing',
      currentFeature: 'Billing Settings',
      custom: {
        userPlan: 'pro',
        hasPaymentMethod: true,
      },
    });
  }, [pillar]);

  return <BillingSettings />;
}

Error Context

Help users troubleshoot errors:

examples/guides/context/error-context.tsx

function PaymentForm() {
  const { pillar } = usePillar();
  const [error, setError] = useState(null);

  const handlePaymentError = (err) => {
    setError(err);
    
    // Tell Pillar about the error
    pillar?.setContext({
      errorState: {
        code: err.code,
        message: err.message,
      },
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      {error && <ErrorMessage error={error} />}
      {/* ... */}
    </form>
  );
}

Now when users ask for help, the AI knows about the error.

User Context

Pass user information for personalized help and tool filtering. If your app uses API tool sources (OpenAPI), you can also pass apiToken in identify() to forward the user's existing auth token — this lets Pillar call the APIs on their behalf without requiring a separate OAuth linking step.

examples/guides/context/user-context-sync.tsx

function UserContextSync() {
  const { pillar } = usePillar();
  const { user } = useAuth();

  useEffect(() => {
    if (user && pillar) {
      pillar.identify(user.id, {
        name: user.name,
        email: user.email,
        apiToken: user.accessToken, // forwarded to API tool sources
      });
      pillar.setContext({
        userRole: user.role,
        userState: user.subscription?.status,
      });
    }
  }, [pillar, user]);

  return null;
}

Tool Filtering with Context

Context enables tool filtering based on user attributes. When you define tools with requiredContext, only users matching that context will see those tools suggested.

examples/guides/context/tool-definition.tsx

// Your tool definition
{
  name: 'delete_user',
  description: 'Delete a user from the organization',
  requiredContext: { userRole: 'admin' },
  // ...
}

examples/guides/context/set-context-for-tools.tsx

// In your app - only admins see the delete_user action
pillar.setContext({ userRole: user.role }); // 'admin' or 'member'

See Tools for more on requiredContext.

Clearing Context

Reset context when needed:

examples/guides/context/clearing-context.tsx

// Clear specific keys
pillar?.setContext({
  errorState: undefined,
});

// Or set completely new context
pillar?.setContext({
  currentPage: '/dashboard',
});

Best Practices

Include Relevant Details

The more context you provide, the better the AI can help:

examples/guides/context/include-relevant-details.tsx

pillar?.setContext({
  currentPage: '/projects/123/settings',
  currentFeature: 'Project Settings',
  userRole: 'owner',
  custom: {
    projectId: '123',
    projectName: 'My Project',
  },
});

Handle Auth State

Clear user context on logout:

examples/guides/context/handle-auth-state.tsx

function handleLogout() {
  pillar?.logout(); // clears user identity, API token, and context
  // Continue logout...
}

Next Steps

Setting Up Tools — Use requiredContext to filter tools by user role or feature
Agent Guidance — Customize how the agent reasons about your product

Search documentation