Send Context

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:

Type	Purpose	Example
`list`	Array of items	Events, features, products
`integration`	External service connections	Stripe, HubSpot, Facebook Ads
`error`	Active issues	Failed syncs, expired tokens
`status`	State indicators	Account health, onboarding step
`config`	Configuration state	Settings, preferences
`feature`	Feature flags	Enabled/disabled features
`metric`	Numeric KPIs	MRR, usage counts, limits
`relationship`	Entity links	Space ID to company mapping
`custom`	Anything else	Any 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:

Stored context is loaded from the user and company records
Per-request context (from the SDK) is layered on top — same keys overwrite
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.

Getting Started

Web Widget

AI Agents

Ask AI

Inbox

Knowledge

Channels

Help Center

Contacts & Companies

Outreach

Settings

Advanced

Planning Your Context Strategy

Why context matters

setContext()

clearContext()

Context at init time

Context types

Dynamic updates

How context reaches the AI

Where to go next

Context Entries

Context Planning

Examples

Planning Your Context Strategy

​Why context matters

​setContext()

​clearContext()

​Context at init time

​Context types

​Dynamic updates

​How context reaches the AI

​Where to go next

Context Entries

Context Planning

Examples

Why context matters

setContext()

clearContext()

Context at init time

Context types

Dynamic updates

How context reaches the AI

Where to go next