> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Interpreters

> Tell the agent what an incoming event is before it reads the body — a shared matching mechanism across email, messaging, webhooks, feeds, and connector events.

**Interpreters** let you tell the agent *what it is looking at* before it reads an incoming event's body. When you expect different kinds of payloads to arrive on the same ingress, an interpreter recognises each kind and injects a plain-language hint into the agent's context.

<Info>
  This is the same mechanism everywhere it appears. Interpreters are configured on the **Email**, **IM Channels**, **Webhook Triggers**, **Feeds**, and **Connectors** (Event Handlers) pages — the editor, fields, and matching behaviour are identical on all of them. The examples below use webhook/HTTP payloads, but the exact same rules apply to inbound email, chat messages, feed items, and connector events.
</Info>

## How an interpreter works

Each interpreter is a named rule with two parts:

1. **Match condition** — how to recognise this payload.
2. **Hint for agent** — what to tell the agent when the match fires.

When an event arrives, each interpreter is tested **in order** — the **first one that matches wins**. Its hint is prepended to the agent's context before the body, so the LLM receives something like:

```
POST webhook received

[Payload schema: Shopify Order Created]
This is a Shopify order.created event.
Key fields: order.id (order ID), order.line_items (products purchased), order.customer.email (buyer).

{"order":{"id":4521…}}
```

<Note>
  Leave interpreters empty when **every** event on this ingress is the same kind of thing — describe it once in the **Context** field instead. Reach for interpreters only when one ingress receives several different event types that need different framing.
</Note>

Click **Add Interpreter**, give it a name, choose a **Match type**, and write the **Hint for agent**. Each interpreter offers two match types.

## JSON Field Presence

Choose **JSON field presence** when the body is always JSON and you want to match by which keys exist. Enter one dot-path per line; **all** of them must be present for the match to fire.

**Example — match a Shopify order event:**

```
order.id
order.line_items
order.customer
```

**Dot-path rules:**

* `order.id` — the key `id` inside the object at `order`
* `order.line_items` — the array (or any value) at `order.line_items`
* Paths only need the key to exist; the value can be `null`, `false`, `0`, or an empty array

This is the right choice when:

* You know the JSON schema in advance
* You want to distinguish between event types by which fields they contain (e.g. `order` vs `refund` vs `customer`)

## Regex Matchers

<a id="regex-matchers" />

Choose **Regex** when the body is not JSON, or when you need to match a specific *value* rather than just the presence of a key.

### What is a regex?

A regex (regular expression) is a pattern that describes something to look for in text. The matcher checks whether the pattern appears *anywhere* in the raw body — if it does, the interpreter fires.

You do not need to match the entire body, just a distinctive fragment.

### When to use regex

| Body format           | Example use-case                                     |
| --------------------- | ---------------------------------------------------- |
| JSON (by value)       | Match a specific event type, not just field presence |
| XML / SOAP            | Look for a specific tag or value                     |
| URL-encoded form data | Match a field like `event=payment.completed`         |
| CSV                   | Check for expected column headers                    |
| Plain text            | Look for a keyword or ID pattern                     |

### Practical examples

#### Match a Stripe payment event (JSON value)

Stripe sends `"type": "payment_intent.succeeded"` in its JSON body. To catch any payment-intent event regardless of outcome:

```
"type"\s*:\s*"payment_intent\.\w+"
```

Flags: *(leave empty)*

Breakdown:

* `"type"` — literal text
* `\s*:\s*` — colon with optional spaces around it
* `"payment_intent\.` — literal `payment_intent.` (the `\.` escapes the dot so it doesn't match any character)
* `\w+"` — one or more word characters (the outcome, e.g. `succeeded`)

#### Match a specific Stripe event type exactly

```
"type"\s*:\s*"payment_intent\.succeeded"
```

#### Match any payment event from any service

```
"type"\s*:\s*"payment
```

This is intentionally loose — it will match `"type": "payment_intent.succeeded"`, `"type": "payment.completed"`, etc.

#### Match a form-encoded event (e.g. Twilio, Slack)

When the body is `event_type=message_received&from=...`, look for the event field:

```
event_type=message_received
```

No special escaping needed — underscores and letters are literal.

#### Match an XML tag value

When the body is XML like `<EventType>OrderCreated</EventType>`:

```
<EventType>OrderCreated</EventType>
```

For case-insensitive matching, set **flags** to `i`:

Pattern: `<eventtype>ordercreated</eventtype>` with flag `i`

#### Match a CSV with specific headers

When the first line is `order_id,customer_email,amount,status`:

```
^order_id,customer_email
```

The `^` anchors to the start of the string, so it only matches if the body *begins* with those column names.

#### Match a webhook from GitHub push events

GitHub push event payloads always contain `"ref":`:

```
"ref"\s*:\s*"refs/heads/
```

This fires for any push to any branch.

### Regex flags

The optional **flags** field modifies how the pattern is applied:

| Flag | Effect                                                                          |
| ---- | ------------------------------------------------------------------------------- |
| `i`  | Case-insensitive — `Order` matches `order`, `ORDER`, etc.                       |
| `m`  | Multiline — `^` and `$` match start/end of each line, not just the whole string |
| `s`  | Dotall — `.` matches newlines too                                               |

You can combine flags: `im` = case-insensitive + multiline.

### Special characters that need escaping

In a regex, these characters have special meaning and must be escaped with `\` if you want them literally:

```
. * + ? ^ $ { } [ ] | ( ) \
```

**Common cases:**

* A literal dot: `example\.com` (not `example.com` which matches any character)
* A literal question mark: `what\?`
* A literal parenthesis: `\(value\)`

If your pattern isn't matching when you expect it to, check whether it contains any of these characters and escape them.

### Keep patterns specific

A very broad pattern like `.+` matches everything and defeats the purpose. Be as specific as your use-case allows — include the field name, a distinctive value prefix, or a structural element unique to the payload type.

## Interpreters vs. Context

Both feed the agent framing, but at different granularities:

* Use **Context** when every event on this ingress is the same kind of thing — one instruction that applies to every payload.
* Use **Interpreters** when one ingress receives different event types — each interpreter fires only for the payloads it matches, so the agent gets the right framing per item without splitting into separate ingresses.

Interpreters run alongside the [Event pre-processor](/sidebar-menu/event-pre-processor) (which runs your own code first) and the event classifier (an optional LLM gate) — see each ingress page for which stages it exposes.