Settingsintermediate

Create a detection rule

Build a Sidekick detection rule that extracts structured data from messages and writes it to a custom field. Walks through the Custom regex detector with a worked Order Number example.

5 min read

Create a detection rule

Build a working detection rule from scratch. By the end you’ll have an Order Number rule that picks ORD-123456 (and similar) out of inbound messages and writes the value to a conversation custom field.

Sidekick ships four detector types — IBAN, Phone, Domain and Custom regex. The first three are ready-made detectors with no pattern to write; Custom regex is the one you configure yourself, and it’s what an order number needs.

Before you start

  • The settings.ai permission, which is what the Detection Rules screen and its API are gated on
  • The destination custom field exists. For order numbers, this is a Text field — Custom regex, IBAN and Domain rules can only target a Text field; Phone rules can target a Phone or a Text field. A rule can be saved without a target field, but it won’t write anything until you set one
  • Sample messages where the data appears (so you can test)

Steps — custom regex method

  1. Open Settings → Sidekick → Detection Rules.

  2. Click New rule. The pane asks What do you want to detect? and offers three ways on:

    For an order number, pick Custom regex. 3. Fill in the basics: - Name — descriptive (e.g. Order Number — ORD prefix). This is the only required field - Detector type — Custom regex 4. Configure the pattern: - Pattern — \bORD-\d{6,10}\b - Flags — gi is prefilled; leave it unless you need case-sensitive matching

    The rule stores the first match in the scanned text. If your pattern has a capture group, the first group is stored; otherwise the whole match is. 5. Target field — pick the Text field the value should be written to. The picker only lists fields whose type the detector can write, and each entry shows whether it is a Contact, Conversation or Contact + Conversation field, so you can see where the value will land. Leave it blank to draft the rule without wiring it up yet. 6. Configure scan scope (optional): - Scan conversation subject — off by default. When enabled, the conversation subject is included with inbound text for matching. - Scan internal notes — enable this if the rule should also scan internal notes, not just customer-facing message text. Only notes written by a person are scanned; system, automation and Sidekick notes are excluded. 7. Test the pattern. The Custom regex form carries a live tester underneath it — paste sample text and the matches are highlighted, with a count. For example: - Hi, I have a question about ORD-987654, can you help? → 1 match, ORD-987654 - My account is ACC-12345 → No matches (different prefix) 8. Leave Enabled on (it is on by default), then click Save. 9. Set the order. Back on the list, drag the rule by its handle to position it. Rules run top to bottom, so if two rules write to the same field the one further down wins.


    describe it in the box and click Suggest, and the AI picks the detector type and its config for you;
    pick a starting point — IBAN, Phone, Domain or Custom regex;
    or Skip — start blank.

Verify it worked

Send a test inbound message containing the pattern:

Hi, I’d like to check on order ORD-987654. Has it shipped yet?

Within a few seconds, open the resulting conversation:

  • The conversation’s order-number custom field should be populated with ORD-987654
  • The value should appear in the Detected Insights module in the Sidekick panel, labelled with the rule’s name and whether it landed on the Contact or the Conversation

Other detector types

This walkthrough used Custom regex. The other three need no pattern of their own — pick the type and the detector handles the format:

  • IBAN — international bank account numbers, validated on country prefix, length and mod-97 checksum, stored without spaces.
  • Phone — phone numbers via libphonenumber, stored in E.164. Choose Worldwide (international format only) or Regional with a list of countries.
  • Domain — plain domain names like acme.no, validated against the Public Suffix List and stored as the registrable domain. Domains inside full URLs and email addresses are ignored.

See the detection rule types reference for picking which.

Common gotchas

  • Rule doesn’t match anything — Pattern is too strict — Use the tester under the Pattern field — paste sample text and adjust until it highlights
  • Rule matches too much — Pattern is too loose (e.g. matching bare numbers anywhere in text) — Tighten — add the literal prefix, add word boundaries (\b), pin the length
  • Save is refused with a regex error — The pattern is invalid, or the safety checker rejected it as potentially catastrophic (ReDoS) — Simplify the pattern — avoid nested quantifiers
  • Rule matches but the custom field stays empty — No target field is set, or the field it points at was deleted — Open the rule and pick a target field of a type the detector can write
  • Two rules keep overwriting each other — Both target the same field, and every matching rule writes — Drag them in the list — the one further down runs last and wins
  • Rule doesn’t fire after editing a subject — Editing the subject by itself doesn’t trigger detection — Subject text is scanned only when a new message or note triggers a detection run

Where this rule shows up afterwards

Once enabled, the rule runs on each detection pass over new inbound messages (plus notes and subject if you opted in):

  • Detected values are visible in the Detected Insights module in the Sidekick panel — the module is hidden when the conversation has no detected values
  • The mapped custom field is written with the match

Agent replies are never scanned: the worker builds its scan text from inbound messages only.

See also

Tags

Ai FeaturesHow To
Back to Settings