User Data & Context Schemas

User Data (Context Schemas) let you inject real-time customer information into conversations. Unlike memory (which is learned), user data is passed from your system at conversation start.

What Is User Data?

User data is information about the customer you pass to Goldilocks:

• Customer attributes - Name, email, plan
• Session data - Current page, cart contents
• Account details - Subscription status, tenure
• Custom fields - Any business-specific data

How It Works

1. Your website collects customer data
2. Data is passed when initializing the widget
3. AI receives this context
4. Responses are personalized based on data

Context Schemas

Schemas define what data fields you'll pass and how the AI should use them.

Viewing Schemas

1. Go to AI Agents > User Data (or Personalization)
2. See list of configured schemas
3. Click to view/edit details

Creating a Schema

1. Go to AI Agents > User Data
2. Click Create Schema
3. Fill in:
   • Name - "Customer Context"
   • Description - What this schema contains
4. Add fields
5. Save

Schema Fields

Each field in your schema represents a piece of data.

Field Properties

Example Fields

Customer Name:

path: customer.name
type: string
label: Customer Name
description: The customer's full name
ai_hint: Use to address the customer personally
sensitivity: pii
visibility: always

Subscription Plan:

path: subscription.plan
type: string
label: Plan Type
description: Current subscription plan (free, pro, enterprise)
ai_hint: Use to provide plan-appropriate guidance
sensitivity: none
visibility: always

Cart Contents:

path: cart.items
type: array
label: Shopping Cart
description: Items currently in the customer's cart
ai_hint: Reference when discussing purchases or recommendations
sensitivity: none
visibility: contextual

Passing Data to Widget

Pass user data when initializing the widget:

Basic Example

new Goldilocks({
  apiKey: 'your-key',
  customerId: 'cust_123',
  customerData: {
    customer: {
      name: 'John Smith',
      email: 'john@example.com'
    },
    subscription: {
      plan: 'pro',
      status: 'active'
    }
  }
});

Shopify Example

new Goldilocks({
  apiKey: 'your-key',
  customerId: '{{ customer.id }}',
  customerData: {
    customer: {
      name: '{{ customer.name }}',
      email: '{{ customer.email }}',
      orders_count: {{ customer.orders_count }},
      total_spent: '{{ customer.total_spent }}'
    },
    shop: {
      name: '{{ shop.name }}',
      currency: '{{ shop.currency }}'
    }
  }
});

Using Templates

Goldilocks offers pre-built schema templates:

Available Templates

Adopting a Template

1. Go to AI Agents > User Data
2. Click Create from Template
3. Select a template
4. Customize fields as needed
5. Save

Template Updates

When templates are updated:

• You're notified of changes
• Can adopt new version or keep current
• Existing data mappings preserved

Field Visibility

Control when fields are included in AI context:

Always

Always included in AI context:

• Customer name
• Account type
• Core identifiers

Contextual

Included only when relevant:

• Cart contents (for purchase questions)
• Order history (for order questions)
• Technical details (for tech support)

Never

Never sent to AI:

• Passwords
• Full credit card numbers
• Internal system IDs

Sensitivity Levels

Mark fields appropriately:

Linking to Personas

Connect schemas to specific personas:

1. Go to persona configuration
2. Find Context Schemas section
3. Select schemas to use
4. Set priority if multiple

Generating Embed Code

Get embed code with your schema fields:

1. Go to Widget > Embed
2. Select your schema
3. Choose your platform (Shopify, custom, etc.)
4. Copy the generated code
5. Update placeholder values

Testing User Data

1. Go to Widget > Preview
2. Open developer tools
3. Pass test data in configuration
4. Verify AI references the data appropriately

Best Practices

Pass Relevant Data Only

Don't pass everything—only what helps the AI:

Good:

• Customer name, plan, tenure
• Recent orders, open tickets
• Relevant preferences

Avoid:

• Internal IDs with no meaning
• Excessive historical data
• Sensitive unnecessary data

Keep Data Fresh

Ensure passed data is current:

• Pull data at widget load
• Refresh for long sessions
• Handle missing data gracefully

Handle Missing Data

Not all data is always available:

customerData: {
  customer: {
    name: customerName || 'Guest',
    plan: customerPlan || 'unknown'
  }
}

Document Your Schema

Maintain documentation of:

• What fields you pass
• Where data comes from
• How AI should use it