# Message Tagging

Automatically detect and respond to specific types of user messages using AI semantic matching.

---

Message tags are one of the most useful features in AVCodex. They let you automatically detect specific kinds of messages and take action: route a frustrated client to a human, flag a warranty escalation, block off-topic requests, or track project leads coming in through a public-facing agent.

## What you can do with tags

A few common patterns:

- Route a tech who needs a senior engineer to a human dispatcher.
- Detect "this is broken right now" so a service desk agent can flag emergencies.
- Catch warranty and RMA requests for the parts team.
- Block off-topic chatter on a public room support agent.
- Track design and pricing intent on a pre-sales agent that handles RFP questions.

## How tag detection works

Unlike keyword matching, AVCodex uses **semantic similarity** to understand the meaning behind messages. That means your tags catch variations and paraphrases you never explicitly defined.

### Why semantic matching matters

Keyword systems force you to anticipate every phrasing. Semantic matching does not.

- "I want to talk to a human" matches "Can I speak with a real person?"
- "What's the price?" matches "How much does this DSP cost?"
- "I'm frustrated" matches "This room is down again and I'm losing my mind."

You define a few example phrases. The AI handles the underlying intent.

## Getting started

Set up your first tag by following the step-by-step in the dashboard.

## Tag configuration options

Each tag has several settings.

### Tag name

Give your tag a clear, descriptive name. You will see this in analytics and chat history, so make it readable at a glance.

**Good names:** "Human Escalation", "Pricing Question", "Warranty Claim", "Emergency Service".

**Bad names:** "Tag 1", "Important", "Check".

### Example phrases

Add 3 to 5 phrases that represent the type of message you want to detect. The AI uses these to learn the meaning, so favor variety.

```
Good examples for "Human Needed":
- "I need to talk to a human"
- "Can I speak with a real person?"
- "Connect me to dispatch"
- "I want to talk to someone now"

Less effective (too similar):
- "Talk to human"
- "Speak to human"
- "Human please"
- "Get me a human"
```

### Detection sensitivity

The sensitivity slider controls how closely a message must match your examples to fire the tag.

| Sensitivity | Best for | Trade-off |
|---|---|---|
| Low (50 to 65%) | Catching every variation | More false positives |
| Medium (70 to 80%) | Balanced detection | Good starting point |
| High (85 to 95%) | Precise matching only | May miss variations |

**Tip:** Start at 75% and tune based on what you see in chat history.

### Blocking response (optional)

For safety or compliance tags, you can replace the AI's response entirely when a tag fires. Useful for:

- **Off-topic requests**: redirect to your agent's purpose (your room support agent should not be answering political questions).
- **Sensitive topics**: provide specific guidance or a disclaimer.
- **Hard handoffs**: "I'm escalating this to dispatch right now. Please stay on the line."

When you add a blocking response, the AI does not generate anything. Your exact text shows instead.

## Best practices

### Start small

Begin with 2 to 3 high-value tags rather than covering every scenario. Add more as you learn what your users are asking.

### Review matches regularly

Check tag matches in chat history to spot false positives and missed detections. That feedback helps you tune sensitivity and add better example phrases.

### Use specific examples

The more specific and varied your example phrases, the better the detection. Generic phrases bring in noise.

### Do not over-block

Use blocking responses only when needed. For most tags, let the AI respond naturally while you track the conversation in the background.

## Common tag configurations

A few setups to get started.

### Service desk agent

| Tag | Purpose | Blocking? |
|---|---|---|
| Human Needed | Route frustrated callers to dispatch. | No |
| Warranty Claim | Flag for the parts team. | No |
| Emergency Service | Surface a hard-down room or event. | No |

### Pre-sales / RFP assistant

| Tag | Purpose | Blocking? |
|---|---|---|
| Purchase Intent | Identify hot leads on a 20-room refresh. | No |
| Pricing Question | Track interest in specific manufacturer SKUs. | No |
| Competitor Mention | Monitor positioning vs other integrators. | No |

### Public room support agent

| Tag | Purpose | Blocking? |
|---|---|---|
| Off-Topic | Redirect non-AV chatter back to room support. | Yes |
| Complex Question | Flag a senior engineer follow-up. | No |
| Feedback | Collect suggestions from end users. | No |

## Viewing tag analytics

Once tags are live, you can see them at work:

1. **Chat History**: each message shows any tags that fired.
2. **Tag Detail View**: click a tag to see every match, sorted by recency.
3. **Remove false positives**: click the X on any incorrectly tagged message to improve future detection.

## Advanced tips

### Combine with Custom Actions

Use tags as triggers for more complex workflows. When a tag fires, you can:

- Send a Slack notification to dispatch.
- Create a ticket in your service CRM.
- Update a spreadsheet.
- Trigger an email to the project manager.

### Multiple tags per message

One message can fire multiple tags. "I need a quote for replacement DSPs and I want to speak to someone today" might fire both "Pricing Question" and "Human Needed."

### Tag categories

Organize related tags with consistent naming prefixes:

- `Service: Human Needed`
- `Service: Warranty Claim`
- `Sales: Pricing Question`
- `Sales: Demo Request`

## Troubleshooting

### Tags are not detecting anything

- Lower the sensitivity threshold.
- Add more varied example phrases.
- Check that the tag is enabled.

### Too many false positives

- Raise the sensitivity threshold.
- Tighten example phrases.
- Drop overly generic examples.

### Tags detecting the wrong things

- Review example phrases for unintended patterns.
- Add negative examples (phrases that should not match).
- Split into more specific tags.

## Next steps

Now that you know how tagging works, set up your first tag:

1. Think about what user messages you most want to detect.
2. Create a tag with 3 to 5 good example phrases.
3. Start at 75% sensitivity.
4. Monitor chat history for a few days.
5. Tune based on what you see.

Tags get more valuable over time as you refine them on real conversations. Start simple, iterate often, and you build a powerful automation layer on top of your AVCodex agent.

## Using with MCP

You can manage tags through code using the AVCodex MCP Server, including AI-powered utterance generation.

### Available tools

| Tool | Description |
|---|---|
| `list_tags` | List all tags for an agent. |
| `create_tag` | Create a new tag with utterances and actions. |
| `update_tag` | Update tag name, utterances, or actions. |
| `delete_tag` | Remove a tag. |
| `list_tag_instances` | View messages that matched a tag. |
| `remove_tag_instance` | Remove a false positive match. |
| `generate_utterances` | AI-generate training phrases for a tag. |

### Example prompts

```
"Create a tag called 'pricing_intent' for my pre-sales agent"
"Generate 200 utterances for detecting warranty escalations"
"Show messages that matched the 'human_needed' tag"
"Remove the false positive from tag instance xyz"
```

### Workflow: AI-powered tag training

```
You: Create a tag for detecting pricing questions in my pre-sales agent.

AI: [Calls create_tag]
Created tag "pricing_intent". Want me to generate training utterances?

You: Yes, generate 200 varied examples for AV integration pricing.

AI: [Calls generate_utterances with count=200, domain="AV integration"]
Generated 200 utterances including:
- "What's the install cost for a 12-room refresh?"
- "How much would a Q-SYS Core 510i system run?"
- "Do you offer volume pricing on Crestron DM-NVX?"
- "Is there a service contract option?"
...

Saved to tag "pricing_intent". The tag is now active.
```

> **Note:** MCP server access requires a Builder plan or higher. See the [MCP Setup Guide](../guides/mcp/setup) to get started.

*AVCodex · Your AV expertise. Amplified by AI.*