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.

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.

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…}}

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.

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

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 (which runs your own code first) and the event classifier (an optional LLM gate) — see each ingress page for which stages it exposes.