# Tags

Tags are key-value pairs that can be attached to bots, users, conversations, and workflows. They provide a flexible way to track metadata, categorize entities, and store cross-handler state.

## Basic Concepts

### What are Tags?

- **Key-value pairs**: String keys with string values
- **Entity-scoped**: Available on bot, user, conversation, and workflow
- **Schema-defined**: Must be declared in `agent.config.ts`
- **Automatically persisted**: Changes are tracked and saved automatically
- **System vs Custom**: System tags (with `:`) are read-only

### Tag Types

| Type | Example Key | Description |
|------|-------------|-------------|
| **Custom** | `tier`, `region` | User-defined, read-write |
| **System** | `webchat:owner` | Integration-managed, read-only |

## Defining Tags

Tags must be defined in your `agent.config.ts` to be persisted:

### User Tags

```typescript
import { defineConfig, z } from "@botpress/runtime";

export default defineConfig({
  name: "my-bot",

  user: {
    // User state (mutable object data)
    state: z.object({
      preferences: z.object({}).passthrough(),
    }),

    // User tags (key-value pairs for categorization)
    // Tags are defined as { title: string, description?: string } objects, NOT Zod schemas
    tags: {
      tier: { title: "Subscription Tier", description: "User subscription level" },
      region: { title: "Region", description: "User geographic region" },
      source: { title: "Acquisition Source" },
      referralCode: { title: "Referral Code" },
    },
  },
});
```

### Conversation Tags

```typescript
export default defineConfig({
  name: "my-bot",

  conversation: {
    tags: {
      category: { title: "Category" },
      priority: { title: "Priority", description: "Conversation priority level" },
      assignedTo: { title: "Assigned To" },
      department: { title: "Department" },
    },
  },
});
```

### Bot Tags

```typescript
export default defineConfig({
  name: "my-bot",

  bot: {
    state: z.object({
      version: z.number().default(1),
    }),

    tags: {
      environment: { title: "Environment", description: "Deployment environment" },
      region: { title: "Region" },
      version: { title: "Version" },
    },
  },
});
```

### Workflow Tags

```typescript
export default defineConfig({
  name: "my-bot",

  workflow: {
    tags: {
      type: { title: "Workflow Type" },
      priority: { title: "Priority" },
      createdBy: { title: "Created By" },
    },
  },
});
```

## Using Tags

### In Conversations

```typescript
import { Conversation, user } from "@botpress/runtime";

export default new Conversation({
  channel: "webchat.channel",

  // conversation is provided as a handler parameter — no need for context.get()
  async handler({ message, conversation }) {
    // Read user tags
    console.log(`User tier: ${user.tags.tier}`);
    console.log(`User region: ${user.tags.region}`);

    // Set user tags
    user.tags.tier = "pro";
    user.tags.source = "website";

    // Read conversation tags
    console.log(`Category: ${conversation.tags.category}`);

    // Set conversation tags
    conversation.tags.priority = "high";
    conversation.tags.department = "support";

    // Conditional logic based on tags
    if (user.tags.tier === "enterprise") {
      // Priority handling for enterprise users
      conversation.tags.priority = "urgent";
    }
  },
});
```

### In Workflows

```typescript
import { Workflow, z, bot } from "@botpress/runtime";

export const ProcessingWorkflow = new Workflow({
  name: "processing",
  input: z.object({ userId: z.string() }),

  async handler({ input, workflow, step }) {
    // Set workflow tags
    workflow.tags.type = "data-processing";
    workflow.tags.priority = "high";

    // Access bot tags
    console.log(`Environment: ${bot.tags.environment}`);

    await step("process", async () => {
      // Processing logic
    });

    return { success: true };
  },
});
```

### In Actions

```typescript
import { Action, z, user, context } from "@botpress/runtime";

export default new Action({
  name: "upgradeUser",
  input: z.object({
    newTier: z.enum(["free", "pro", "enterprise"]),
  }),
  output: z.object({ success: z.boolean() }),

  async handler({ input }) {
    const oldTier = user.tags.tier;
    const conversation = context.get("conversation", { optional: true });

    // Update user tag
    user.tags.tier = input.newTier;

    // Log the upgrade in conversation
    if (conversation) {
      conversation.tags.category = "upgrade";
    }

    console.log(`Upgraded user from ${oldTier} to ${input.newTier}`);

    return { success: true };
  },
});
```

## Tags vs State

Understanding when to use tags versus state:

| Aspect | Tags | State |
|--------|------|-------|
| **Structure** | Flat key-value pairs | Nested objects |
| **Types** | Strings only | Any type (objects, arrays, numbers) |
| **Use case** | Categorization, filtering | Complex data storage |
| **Queryable** | Yes (via API) | Limited |
| **Size** | Small values | Larger structures |

### When to Use Tags

```typescript
// ✅ Good for tags - simple categorization
user.tags.tier = "pro";
user.tags.region = "us-east";
conversation.tags.priority = "high";

// ❌ Bad for tags - complex data belongs in state
user.tags.preferences = JSON.stringify({ theme: "dark" }); // Don't do this!
```

### When to Use State

```typescript
// ✅ Good for state - complex structures
user.state.preferences = {
  theme: "dark",
  notifications: true,
  language: "en",
};

user.state.history = [
  { action: "login", timestamp: new Date() },
  { action: "purchase", timestamp: new Date() },
];
```

## System Tags

System tags are managed by integrations and are **read-only**. They contain a colon (`:`) in their key.

### Common System Tags

```typescript
// Webchat system tags (read-only)
console.log(user.tags["webchat:owner"]); // User who initiated webchat
console.log(conversation.tags["webchat:sessionId"]); // Session identifier

// Integration-specific system tags
console.log(user.tags["slack:userId"]); // Slack user ID
console.log(conversation.tags["discord:channelId"]); // Discord channel
```

### System Tag Behavior

```typescript
// System tags are silently ignored when you try to set them
user.tags["webchat:owner"] = "new-value"; // No error, but no effect

// Only custom tags (without ':') can be modified
user.tags.tier = "enterprise"; // ✅ Works
user.tags.customField = "value"; // ✅ Works
```

## Advanced Patterns

### Tag-Based Routing

```typescript
import { Conversation, conversation, user } from "@botpress/runtime";

export default new Conversation({
  channel: "webchat.channel",

  async handler({ message, execute }) {
    // Route based on conversation priority
    const priority = conversation.tags.priority;

    if (priority === "urgent") {
      // Fast-track urgent conversations
      await execute({
        instructions: "This is an urgent request. Prioritize resolution.",
        model: "openai:gpt-4o", // Use best model
      });
    } else {
      await execute({
        instructions: "Help the user with their request.",
        model: "openai:gpt-4o-mini", // Cost-efficient model
      });
    }
  },
});
```

### Tag-Based Analytics

```typescript
import { Trigger } from "@botpress/runtime";
import { AnalyticsTable } from "../tables/Analytics";

export default new Trigger({
  name: "trackConversation",
  events: ["conversation.ended"],

  async handler({ event }) {
    const { conversationId, tags } = event.payload;

    // Store conversation metrics by tags
    await AnalyticsTable.createRows({
      rows: [
        {
          conversationId,
          category: tags.category || "uncategorized",
          priority: tags.priority || "normal",
          department: tags.department || "general",
          timestamp: new Date(),
        },
      ],
    });
  },
});
```

### Progressive Tag Collection

```typescript
import { Conversation, user, adk } from "@botpress/runtime";

export default new Conversation({
  channel: "webchat.channel",

  async handler({ message }) {
    // Infer and set tags from conversation
    if (!user.tags.region && message?.type === "text") {
      const region = await adk.zai.extract(
        message.payload.text,
        z.string().optional(),
        { instructions: "Extract geographic region if mentioned" }
      );

      if (region) {
        user.tags.region = region;
      }
    }

    // Set source tag if not already set
    if (!user.tags.source) {
      user.tags.source = "webchat";
    }
  },
});
```

### Tag Inheritance in Workflows

```typescript
import { Workflow, z, user } from "@botpress/runtime";

export const SupportWorkflow = new Workflow({
  name: "support",
  input: z.object({
    conversationId: z.string(),
    issue: z.string(),
  }),

  async handler({ input, workflow, step }) {
    // Inherit priority from user tier
    const tier = user.tags.tier;

    if (tier === "enterprise") {
      workflow.tags.priority = "high";
    } else if (tier === "pro") {
      workflow.tags.priority = "normal";
    } else {
      workflow.tags.priority = "low";
    }

    // Set workflow type
    workflow.tags.type = "support-ticket";

    await step("process", async () => {
      // Processing based on priority
    });

    return { processed: true };
  },
});
```

## Best Practices

### 1. Use Descriptive Tag Names

```typescript
// ✅ Good - clear purpose
tags: {
  subscriptionTier: { title: "Subscription Tier", description: "User subscription level" },
  acquisitionChannel: { title: "Acquisition Channel" },
  supportPriority: { title: "Support Priority" },
}

// ❌ Bad - unclear
tags: {
  t: { title: "T" },
  lvl: { title: "Lvl" },
  p: { title: "P" },
}
```

### 2. Use Enums for Constrained Values

```typescript
// ✅ Good - descriptive titles
tags: {
  status: { title: "Account Status", description: "Active, inactive, or suspended" },
  tier: { title: "Subscription Tier", description: "Free, pro, or enterprise" },
}

// ❌ Bad - missing descriptions
tags: {
  status: { title: "Status" }, // Unclear what values are expected
}
```

### 3. Document Tag Purposes

```typescript
export default defineConfig({
  user: {
    tags: {
      tier: { title: "Subscription Tier", description: "Customer subscription level for feature gating" },
      region: { title: "Region", description: "Geographic region for compliance and routing" },
      acquisitionSource: { title: "Acquisition Source", description: "How the user discovered the bot" },
    },
  },
});
```

### 4. Set Tags Early

```typescript
// Set identification tags early in the conversation
async handler({ message, type }) {
  if (type === "conversation_started") {
    // Set source immediately
    conversation.tags.source = "webchat";
    conversation.tags.startedAt = new Date().toISOString();
  }
}
```

### 5. Use Tags for Filtering, Not Storage

```typescript
// ✅ Good - tags for filtering/categorization
user.tags.tier = "enterprise";
conversation.tags.category = "billing";

// ❌ Bad - storing complex data in tags
user.tags.preferences = JSON.stringify({ notifications: true }); // Use state instead
```

## Troubleshooting

### Tags Not Persisting

1. **Check schema definition**: Tags must be defined in `agent.config.ts`
2. **Verify tag key**: Custom tags cannot contain `:`
3. **Check value type**: Tags only accept string values

```typescript
// ✅ Correct
user.tags.tier = "pro"; // String value

// ❌ Wrong - will be ignored or cause errors
user.tags.count = 5; // Number (should be string)
user.tags.active = true; // Boolean (should be string)
```

### System Tags Appearing Read-Only

System tags (containing `:`) are managed by integrations:

```typescript
// These are read-only - modifications are silently ignored
user.tags["webchat:owner"] = "new"; // No effect
conversation.tags["slack:channel"] = "new"; // No effect

// Only custom tags can be modified
user.tags.myCustomTag = "value"; // ✅ Works
```

### Tag Not in Schema Error

If you see errors about undefined tags, add them to your config:

```typescript
// Before: Tag not in schema
user.tags.newTag = "value"; // Warning: Tag not defined

// Fix: Add to agent.config.ts
export default defineConfig({
  user: {
    tags: {
      newTag: { title: "New Tag" }, // Now it will persist
    },
  },
});
```

## See Also

- **[Agent Configuration](./agent-config.md)** - Full agent.config.ts reference
- **[Conversations](./conversations.md)** - Using tags in conversation handlers
- **[Workflows](./workflows.md)** - Workflow tags and state management
- **[Context API](./context-api.md)** - Accessing bot, user, conversation context