Skip to main content

Planning Your Context Strategy

For a step-by-step guide to deciding what data to send and how to keep it fresh, see Planning Your Context Strategy.

​
Why context matters

Identifying users tells the AI who they are. Context tells the AI what’s happening for them right now — what they’ve configured, what’s broken, what features they use. Each context entry has:
  • A key (unique identifier)
  • A label (human-readable name shown in the AI prompt)
  • An optional type hint (helps the AI understand the data shape)
  • A value (any JSON: string, number, boolean, array, or object)
Context is the difference between “I’m not sure why your sync isn’t working” and “I see your HubSpot OAuth token expired — let me walk you through reconnecting.”

​
setContext()

ha.setContext(key: string, entry: ContextEntry): void
Set or update a context entry: 
ha.setContext("active_events", {
  label: "Active Tracking Events",
  type: "list",
  value: [
    { event_name: "purchase", label: "Purchase Event", status: "active" },
    { event_name: "lead", label: "Lead Submitted", status: "paused" },
  ]
});
If a context entry with the same key exists, it’s replaced entirely.

​
clearContext()

ha.clearContext(key?: string): void
Remove a specific entry, or clear all context: 
ha.clearContext("active_events");

ha.clearContext();

​
Context at init time

You can set initial context when calling init(): 
window.HaloAgents.init({
  orgId: "your-org-id",
  apiKey: "ab_live_...",
  userId: "user_123",
  context: {
    active_events: {
      label: "Active Tracking Events",
      type: "list",
      value: [
        { event_name: "purchase", label: "Purchase Event", status: "active" },
      ]
    },
    subscription: {
      label: "Subscription",
      type: "metric",
      value: { plan: "pro", mrr: 299, seats_used: 5, seats_limit: 10 }
    }
  }
});

​
Context types

The type field is a semantic hint that helps the AI understand and format the data. See Context Entries for the full reference. Quick summary:
TypePurposeExample
listArray of itemsEvents, features, products
integrationExternal service connectionsStripe, HubSpot, Facebook Ads
errorActive issuesFailed syncs, expired tokens
statusState indicatorsAccount health, onboarding step
configConfiguration stateSettings, preferences
featureFeature flagsEnabled/disabled features
metricNumeric KPIsMRR, usage counts, limits
relationshipEntity linksSpace ID to company mapping
customAnything elseAny structured data

​
Dynamic updates

Context can be updated at any time. Useful for reflecting real-time state changes: 
ha.setContext("integrations", {
  label: "Connected Integrations",
  type: "integration",
  value: {
    stripe: { connected: true, status: "active" },
    hubspot: { connected: true, status: "active" },
  }
});

ha.setContext("errors", {
  label: "Current Issues",
  type: "error",
  value: [
    { area: "sync", message: "HubSpot sync failed: rate limit exceeded" }
  ]
});
The next chat message includes the updated context.

​
How context reaches the AI

Context is sent with every chat message and merged with any context stored on the user/company records:
  1. Stored context is loaded from the user and company records
  2. Per-request context (from the SDK) is layered on top — same keys overwrite
  3. The merged context is formatted into structured text in the AI system prompt
See Contacts & Companies Overview for the full data flow.

​
Where to go next

Context Entries

Deep reference for every context type with example AI output.

Context Planning

Strategy guide: what to send, how to structure, how to keep fresh.

Examples

Real-world patterns for SaaS, e-commerce, ad attribution.