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 and is placed on the relevant Contact or Conversation canvas. The field type must be compatible with the detector: Custom regex can write to Text, Text Area, Number, Phone, URL or Email; Domain can write to Text, Text Area or URL; IBAN can write to Text or Text Area; Phone can write to Phone, Text or Text Area. 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 field marked required, but a Custom regex rule also needs a Pattern before it will save - 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 field the value should be written to. The picker only lists compatible fields that are placed on the relevant Contact or Conversation canvas, and each entry shows whether it is a Contact, Conversation or Contact + Conversation field, so you can see where the value will land. Compatibility depends on the detector: Custom regex can write to Text, Text Area, Number, Phone, URL or Email; Domain can write to Text, Text Area or URL; IBAN can write to Text or Text Area; Phone can write to Phone, Text or Text Area. Leave it blank to draft the rule without wiring it up yet. A field the rule already targets stays listed even if it is no longer placed on a canvas. 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)

    The tester uses your browser’s regex engine, while the server uses a stricter one. A pattern can therefore show a match in the tester and still be refused when you save. 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 match in the same pass and write to the same empty 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, is over 500 characters, or uses a backreference, a lookaround or a repeat that expands past 1000 — Remove the unsupported feature or shorten the pattern
  • The tester shows a match but the rule doesn’t save or doesn’t match — The live tester uses the browser’s engine, which accepts patterns the server refuses — Treat the tester as a guide only; if Save is refused, remove backreferences, lookarounds and large repeats
  • 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
  • The value is in a long message but the field stays empty — A single text over 10,000 characters is skipped for custom rules — Nothing is written to the field for that text; the rule can still match other, shorter messages in the conversation
  • The wrong rule’s value lands in a shared field — Both target the same empty field and match in the same pass — 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 filled with the match when it is empty — a field that already holds a value keeps it

How the scan works for custom rules:

  • Each message, then the subject, then the notes are scanned one at a time, in that order, and the first match wins.
  • A single text over 10,000 characters is skipped; the other texts are still scanned.
  • The live tester under the Pattern field still uses the browser’s engine, so it can show a match that the server refuses.

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

See also

Tags

Ai FeaturesHow To