Context Entries

What a context entry is

A context entry is a labeled, typed piece of structured data formatted into the AI agent’s system prompt. Unlike traits (simple key-value), context entries can hold complex structures: arrays of objects, nested objects, or any JSON value.

interface ContextEntry {
  label: string;       // Human-readable header in the AI prompt
  type?: ContextType;  // Semantic hint for formatting
  value: unknown;      // Any JSON value
}

Context types

The type field tells the AI formatter how to render the data and gives the AI semantic understanding of what it represents.

list

Arrays of items — events, products, features, or any collection.

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" },
    { event_name: "signup", label: "New Signup", status: "active" },
  ]
});

AI sees:

[Active Tracking Events] (list)
- "Purchase Event" (event_name: purchase) -- active
- "Lead Submitted" (event_name: lead) -- paused
- "New Signup" (event_name: signup) -- active

The formatter intelligently picks label/name/title as the primary descriptor and shows status separately.

integration

External service connections and their states. Errors are highlighted.

ha.setContext("integrations", {
  label: "Connected Integrations",
  type: "integration",
  value: {
    facebook_ads: { connected: true, status: "active" },
    google_ads: { connected: true, status: "error", error: "Token expired" },
    hubspot: { connected: false },
    stripe: { connected: true, status: "active" },
  }
});

AI sees:

[Connected Integrations] (integration)
- Facebook ads: connected, active
- Google ads: connected, ERROR -- Token expired
- Hubspot: not connected
- Stripe: connected, active

error

Active issues or errors the AI should acknowledge and help with.

ha.setContext("errors", {
  label: "Current Issues",
  type: "error",
  value: [
    { area: "tracking_pixel", message: "Pixel not firing on checkout page", since: "2025-01-15" },
    { area: "data_sync", message: "Sync to warehouse paused due to quota" },
  ]
});

AI sees:

[Current Issues] (error)
- tracking_pixel: Pixel not firing on checkout page (since 2025-01-15)
- data_sync: Sync to warehouse paused due to quota

status

General status indicators about the user or account.

ha.setContext("account_status", {
  label: "Account Status",
  type: "status",
  value: {
    onboarding: { status: "in_progress", step: "3/5" },
    billing: { status: "active", next_invoice: "2025-02-01" },
    trial: { status: "expired", expired_on: "2025-01-01" },
  }
});

AI sees:

[Account Status] (status)
- Onboarding: in_progress, Step: 3/5
- Billing: active, Next invoice: 2025-02-01
- Trial: expired, Expired on: 2025-01-01

config

Configuration or settings state.

ha.setContext("settings", {
  label: "User Settings",
  type: "config",
  value: [
    { setting: "notifications", label: "Email Notifications", value: "enabled" },
    { setting: "timezone", label: "Timezone", value: "America/New_York" },
    { setting: "currency", label: "Display Currency", value: "USD" },
  ]
});

feature

Feature flags or enabled capabilities.

ha.setContext("features", {
  label: "Feature Flags",
  type: "feature",
  value: {
    beta_dashboard: true,
    new_analytics: true,
    ai_insights: false,
    custom_reports: { enabled: true, variant: "v2" },
  }
});

AI sees:

[Feature Flags] (feature)
- Beta dashboard: enabled
- New analytics: enabled
- Ai insights: disabled
- Custom reports: enabled (variant: v2)

metric

Numeric KPIs or measurements.

ha.setContext("usage", {
  label: "Usage Metrics",
  type: "metric",
  value: {
    api_calls_today: 1250,
    api_limit: 5000,
    storage_used_gb: 4.2,
    storage_limit_gb: 10,
    active_users: 23,
  }
});

AI sees:

[Usage Metrics] (metric)
- Api calls today: 1250
- Api limit: 5000
- Storage used gb: 4.2
- Storage limit gb: 10
- Active users: 23

relationship

Entity relationships and cross-references.

ha.setContext("workspace", {
  label: "Workspace Info",
  type: "relationship",
  value: {
    space_id: "space_789",
    parent_org: "org_123",
    linked_accounts: ["acc_001", "acc_002"],
  }
});

custom

Use "custom" (or omit the type entirely) for anything that doesn’t fit the other categories. The formatter auto-detects the best rendering based on the value type.

ha.setContext("notes", {
  label: "Support Notes",
  type: "custom",
  value: "VIP customer. Handle with extra care. Prefers email for follow-ups."
});

No type? No problem

If you omit type, the formatter auto-detects from the value:

Array — rendered as a bulleted list
Object — rendered as key-value pairs
String/number/boolean — rendered as a simple value

Best practices

Use descriptive labels

Labels appear as section headers in the AI prompt. Make them clear and specific:

Good: "Active Tracking Events", "Connected Integrations"
Bad: "Events", "Data", "Stuff"

Include both IDs and labels for list items

For lists, include both the machine ID (event_name) and the human label (label). This lets the AI reference items naturally.

Use error type for things the AI should proactively acknowledge

When a user asks for help and they have active errors, the AI references them automatically.

Keep context entries focused

Prefer multiple focused entries over one giant blob. Each entry should represent one concept (events, integrations, errors, etc.).

Update context dynamically

Call setContext() whenever the user’s state changes — connecting an integration, encountering an error, changing a setting. The AI always sees the latest data.

Getting Started

Web Widget

AI Agents

Ask AI

Inbox

Knowledge

Channels

Help Center

Contacts & Companies

Outreach

Settings

Advanced

What a context entry is

Context types

list

integration

error

status

config

feature

metric

relationship

custom

No type? No problem

Best practices

Where to go next

Examples

Context Planning

​What a context entry is

​Context types

​list

​integration

​error

​status

​config

​feature

​metric

​relationship

​custom

​No type? No problem

​Best practices

​Where to go next

Examples

Context Planning

What a context entry is

Context types

list

integration

error

status

config

feature

metric

relationship

custom

No type? No problem

Best practices

Where to go next