# Attribute Matcher

#### What are Attributes?

Attributes are custom fields you can attach to your **users** and **leads**. They extend the standard profile information SalesChat already tracks — letting you store details like sales process, campaign source, product code, or location.

Attributes are typically set via integrations and APIs (e.g., synced from your CRM). Once set, they become available throughout SalesChat — including in the Attribute Matcher, where you can build rules based on them.

For details on how attributes relate to events, see Events & Attributes.

***

#### What is an Attribute Matcher?

An Attribute Matcher is a rule engine that lets you control platform behaviour based on user and lead attributes. You define conditions, and SalesChat evaluates them in real time.

**Where it's used:**

| Feature                 | How Matcher is Used                                               |
| ----------------------- | ----------------------------------------------------------------- |
| **Contact Free Flow**   | Controls which users can send freeflow (non-templated) messages   |
| **Automation Triggers** | Determines whether an automation should fire when an event occurs |

***

#### Using Attribute Matcher in Automation

When you create an automation with the `UPDATE_CONTACT_STAGE_DISPOSITION` event type, you configure trigger conditions using the Attribute Matcher.

**How it works:**

1. An event occurs (e.g., a lead's disposition is updated)
2. SalesChat merges the lead's **permanent attributes** with the **event attributes**
3. The matcher evaluates your conditions against the merged attributes
4. If conditions match, the automation action fires (e.g., send a template message)

**Example automation:** Send a template message when stage is "INTERESTED" and the lead's process is "RM".

Conditions:

| Property | Operator | Value      |
| -------- | -------- | ---------- |
| Stage    | equals   | INTERESTED |
| Process  | equals   | RM         |

This matches when:

* The disposition event has `stage = INTERESTED` (event attribute)
* The lead has `process = RM` (permanent attribute)

***

#### Scope (Entity Types)

A matcher can evaluate attributes from two entity types:

* **User** — the SalesChat user (agent/rep). Built-in properties: email, name. Custom attributes: any attributes set on the user (e.g., process, location, team).
* **Lead** — the contact/lead being communicated with. Built-in properties: phone number, first name, last name, CRM ID, stage, disposition. Custom attributes: any attributes set on the lead (e.g., campaign, product code).

You can scope a matcher to **User only**, **Lead only**, or **both**. The scope determines which properties are available when building conditions.

***

#### Properties

Properties are the fields you can evaluate in a condition. They come in two categories:

**Built-in properties**

These are always available:

| Property     | Entity Type | Description                              |
| ------------ | ----------- | ---------------------------------------- |
| Email        | User        | Agent's email address                    |
| Name         | User        | Agent's display name                     |
| Phone Number | Lead        | Lead's phone number                      |
| First Name   | Lead        | Lead's first name                        |
| Last Name    | Lead        | Lead's last name                         |
| CRM ID       | Lead        | Lead's CRM identifier                    |
| Stage        | Lead        | Lead's current stage (from events)       |
| Disposition  | Lead        | Lead's current disposition (from events) |

**Custom attributes**

Any attributes that have been set on users or leads in your organization appear automatically in the property dropdown. For example, if your CRM sync sets a `process` attribute on users, it will show up as a selectable property.

If the attribute you need isn't listed yet, you can manually add it by clicking **Add custom attribute** at the bottom of the property dropdown, selecting the entity type (User or Lead), and typing the attribute key.

**Event attributes** (like `call_time` or `payment_amount` sent via the disposition API) can also be used as custom attributes in matcher conditions.

***

#### Conditions and Condition Sets

**Conditions**

A condition is a single check: **property** + **operator** + **value**.

For example: *lead's stage* **equals** *"INTERESTED"*

**Condition Sets (AND + OR logic)**

Conditions are grouped into **Condition Sets**:

* Within a set, **all conditions must be true** (AND logic)
* Across sets, **any one set matching is enough** (OR logic)

```
Matcher passes if:
   (Set 1: ALL conditions true)    <- AND within
   OR                              <- OR across
   (Set 2: ALL conditions true)
   OR ...
```

**Example:** Trigger automation if the lead's stage is "INTERESTED" AND process is "RM", OR if the stage is "QUALIFIED" (regardless of process).

Set 1: `stage equals INTERESTED` AND `process equals RM` Set 2: `stage equals QUALIFIED`

***

#### Operator Reference

Operators define how a property's value is compared.

**Text matching**

| Operator            | Evaluation                                                                | Value input                       | Example                                  |
| ------------------- | ------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------- |
| **equals**          | Passes if the actual value matches **any one** of the specified values    | One or more values (multi-select) | Stage equals "INTERESTED" or "QUALIFIED" |
| **not equals**      | Passes if the actual value does **not** match any of the specified values | One or more values (multi-select) | Disposition not equals "DND", "INVALID"  |
| **contains**        | Passes if the actual value contains the specified text as a substring     | Single value                      | Email contains "@saleschat"              |
| **doesn't contain** | Passes if the actual value does **not** contain the specified text        | Single value                      | Name doesn't contain "test"              |

**Numeric comparison**

| Operator         | Evaluation                                                                | Value input   | Example                          |
| ---------------- | ------------------------------------------------------------------------- | ------------- | -------------------------------- |
| **greater than** | Passes if the numeric value is strictly greater than the specified number | Single number | Payment amount greater than 5000 |
| **less than**    | Passes if the numeric value is strictly less than the specified number    | Single number | Call attempt number less than 3  |

> Non-numeric values are treated as 0 during numeric comparison.

**Presence checks**

| Operator       | Evaluation                                         | Value input   | Example             |
| -------------- | -------------------------------------------------- | ------------- | ------------------- |
| **is set**     | Passes if the attribute exists and has any value   | None required | Phone number is set |
| **is not set** | Passes if the attribute is missing or has no value | None required | CRM ID is not set   |

**Pattern matching**

| Operator          | Evaluation                                                             | Value input          | Example                 |
| ----------------- | ---------------------------------------------------------------------- | -------------------- | ----------------------- |
| **matches regex** | Passes if the actual value matches the full regular expression pattern | Single regex pattern | Phone matches `^\+91.*` |

> The regex must match the **entire** value, not just a part of it.

***

#### Example: Automation with Attribute Matcher

**Scenario:** Send a template message when a lead's disposition is updated to "INTERESTED" stage, but only for leads in the RM process with a policy number assigned.

**Condition Set 1:**

| Property                            | Operator | Value      |
| ----------------------------------- | -------- | ---------- |
| Stage (event attribute)             | equals   | INTERESTED |
| Process (permanent attribute)       | equals   | RM         |
| Policy Number (permanent attribute) | is set   | —          |

**Result:** When a disposition update event arrives with `stage = INTERESTED`, the matcher checks the event attribute (stage) and the lead's permanent attributes (process, policy\_number). If all conditions pass, the template message is sent.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.saleschat.pro/principles/attribute-matcher.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.