Search documentation

Search documentation

Core SDK@pillar-ai/sdk

Context

Set user context and manage identity.

typescript
import Pillar from '@pillar-ai/sdk'

Methods

Pillar.setContext()

Set context for the assistant. Use this to tell Pillar what the user is doing for smarter, more relevant assistance.

typescript
setContext(ctx: Partial<Context>): void

Parameters

ctx
requiredPartial<Context>
- Context fields to set (merges with existing context)

Example

tsx
pillar.setContext({
  currentPage: '/settings/billing',
  currentFeature: 'Billing Settings',
  userRole: 'admin',
});

Pillar.getChatContext()

Get the current chat context (conversation ID and messages). Useful for escalation to human support with conversation history.

typescript
getChatContext(): ChatContext | null

Returns

ChatContext | null

Example

tsx
// Get chat context for escalation
const context = pillar.getChatContext();
if (context) {
  const summary = context.messages
    .map(m => `${m.role}: ${m.content.slice(0, 100)}`)
    .join('\n');
  showIntercom(`Escalating from AI assistant:\n${summary}`);
}

Pillar.identify()

Identify the current user after login. Call this when a user logs into your application to: - Link their anonymous conversation history to their account - Enable cross-device conversation history retrieval - Associate future conversations with their user ID

typescript
identify(userId: string, profile?: {
      name?: string;
      email?: string;
      metadata?: Record<string, unknown>;
    }, options?: { preserveConversation?: boolean }): Promise<void>

Parameters

userId
requiredstring
- Your application's user ID for this user
profile
{ name?: string; email?: string; metadata?: Record<string, unknown>; }
- Optional user profile data (name, email, metadata)
options
{ preserveConversation?: boolean }
- Optional settings for the identify call

Returns

Promise<void>

Example

tsx
// When user logs in
await pillar.identify('user-123', {
  name: 'John Doe',
  email: 'john@example.com',
});


// Keep current conversation when identifying
await pillar.identify('user-123', undefined, { preserveConversation: true });

Pillar.logout()

Clear the user's identity (logout). Call this when a user logs out of your application. Future conversations will be tracked anonymously until identify() is called again. Note: This does not delete existing conversations - they remain associated with the user's account for future retrieval.

typescript
logout(options?: { preserveConversation?: boolean }): void

Parameters

options
{ preserveConversation?: boolean }
- Optional settings for the logout call

Example

tsx
// When user logs out
pillar.logout();


// Keep current conversation when logging out
pillar.logout({ preserveConversation: true });

Types

Context

interface

Context for the assistant. Pass this to help the assistant understand what the user is doing.

typescript
interface Context {
  /** Current page path (e.g., "/settings/billing") */
  currentPage?: string;


  /** Current feature or section (e.g., "Billing Settings") */
  currentFeature?: string;


  /** User's role in the product (e.g., "admin", "member") */
  userRole?: string;


  /** Current user state or mode (e.g., "onboarding", "trial") */
  userState?: string;


  /** Any error state the user is experiencing */
  errorState?: {
    code: string;
    message: string;
  };


  /** Custom context data */
  custom?: Record<string, unknown>;
}

Properties

currentPage
string
Current page path (e.g., "/settings/billing")
currentFeature
string
Current feature or section (e.g., "Billing Settings")
userRole
string
User's role in the product (e.g., "admin", "member")
userState
string
Current user state or mode (e.g., "onboarding", "trial")
errorState
{ code: string; message: string; }
Any error state the user is experiencing
custom
Record<string, unknown>
Custom context data

UserProfile

interface

User profile for personalization.

typescript
interface UserProfile {
  /** User identifier (for conversation continuity) */
  userId?: string;


  /** User's name for personalized responses */
  name?: string;


  /** User's role/permissions */
  role?: string;


  /** Account/organization info */
  accountType?: string;


  /** User's experience level */
  experienceLevel?: 'beginner' | 'intermediate' | 'advanced';
}

Properties

userId
string
User identifier (for conversation continuity)
name
string
User's name for personalized responses
role
string
User's role/permissions
accountType
string
Account/organization info
experienceLevel
'beginner' | 'intermediate' | 'advanced'
User's experience level

Suggestion

interface

Suggestion returned from the suggestions API.

typescript
interface Suggestion {
  type: 'article' | 'video' | 'tutorial' | 'action';
  id: string;
  title: string;
  description: string;
  relevanceScore: number;
  url?: string;
}

Properties

type
required'article' | 'video' | 'tutorial' | 'action'
No description.
id
requiredstring
No description.
title
requiredstring
No description.
description
requiredstring
No description.
relevanceScore
requirednumber
No description.
url
string
No description.