Intelligent Bot Classification Transformation Template

You can now classify bot traffic by intent using the Intelligent bot classification transformation template. It asks two separate questions about every event it evaluates — what produced the event, and whether the event looks like abuse.

This template sends event-derived signals to TypeSafe AI, a third-party service, and needs an API key you supply. Review that data transfer, and the limitations below before you enable it.

Why classify bots by intent?

A single “is it a bot?” check gets two common cases wrong:

1. A bot farm driving real browsers looks human but is abusive
2. An AI agent buying on a customer’s behalf is a bot with legitimate intent, and real revenue attached

Separating the category from the intent lets you drop the first case while keeping the second.

Key features

• Category and intent scored separately: context.bot.category returns one of human, ai_agent, ai_crawler, search_crawler, seo_tool, scraper, or other_automation, alongside a badIntent probability from 0 to 1.
• Shadow mode by default: The template tags events without dropping any, so you can compare verdicts against real traffic before you enforce.
• Output matches Bot Management: Writes context.isBot and context.bot, the same shape as Bot Management, so your downstream logic works unchanged.
• Scoped to events that matter: Evaluates identify plus a configurable list of high-value events, so you only spend a classification call where a bot costs you money.
• Configurable endpoint: Point the template at a different classifier, including one you host yourself.

Get started

1. Add your API key as a secret named TYPESAFE_API_KEY under Settings > Workspace > Credentials > Secrets. See Transformation Credentials.
2. Go to Collect > Transformations and click Create Transformation.
3. Select the Intelligent bot classification template.
4. If you use Bot Management, set it to forward bot events with a flag rather than drop them, so those events still reach this template.
5. Leave MODE as shadow until the verdicts look right, then change it to enforce to start dropping events above BAD_INTENT_THRESHOLD.

Using a self-hosted classifier

The endpoint is a constant at the top of the template. Change TYPESAFE_API_URL to point at any service that accepts the same request shape and returns the same response shape, including self-hosted alternatives such as Laya or Kev.

Check the request and response contract before you switch. The template posts a model, a state object, and a questions object containing a choice question and a noul question, then reads answers.kind.choice, answers.kind.confidence, and answers.bad_intent.noul from the response. A service that does not match that contract needs the askJev function adjusted, not just the URL.

Known limitations

• Identity redaction is incomplete for non-ASCII text: The template sends the pattern of an email local part and a name rather than the values, but the pattern helper only substitutes ASCII letters and digits. Characters outside that range, including accented Latin, Cyrillic, and CJK, are sent unchanged. Do not treat this as full redaction for a non-ASCII user base.
• A human verdict overrides an inbound bot flag: When the classifier returns human, the template sets context.isBot to false, replacing any flag Bot Management already set on the event.
• The template appears on every plan, but needs Growth or Enterprise to work: It reads the API key with getCredential, which is available on the Growth and Enterprise plans only. On other plans it logs an error and leaves events unchanged.
• Event properties are not sent by default: ALLOWED_PROPERTY_KEYS is empty. Add only scrubbed, non-sensitive keys if the classifier needs them.

Resources

• Transformation Templates: All prebuilt templates
• Transformation Credentials: Storing the API key as a secret
• Runtime Functions in Transformations: getCredential, fetchV2, and log
• Bot Management: User agent based detection to pair with this template