> For the complete documentation index, see [llms.txt](https://docs.saleschat.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saleschat.pro/principles/events-and-attributes.md).

# Events & Attributes

#### Overview

SalesChat tracks two types of data for your leads and users:

* **Attributes** — Attributes are custom fields you can attach to your **users** and **leads** (e.g., process, product code, policy number)
* **Events** — things that happen, carrying event-scoped attributes (e.g., stage change, disposition update, call details)

Automations are triggered based on events and attributes are used by attribute matcher to filter such events.

#### Permanent Attributes

Permanent attributes are properties that rarely change and are scoped for the life of the lead.

Permanent attributes are key-value pairs stored on a lead or user. They accumulate over time — each update merges new values with existing ones.

**How they work:**

```
API call 1:  { "process": "Issuance" }     → Lead has: { process: Issuance }
API call 2:  { "product_code": "P1" }      → Lead has: { process: RM, product_code: P1 }
API call 3:  { "process": "Sales" }        → Lead has: { process: Sales, product_code: P1 }
```

* New keys are added
* Existing keys are updated (latest value wins)
* Keys not included in the update are preserved

**Use cases:** CRM sync fields, customer segments, agent assignments, any data that defines "who" the lead or user is.

#### Events

Events represent things that happen to a lead. Each event has a **type** and carries **event attributes** that are scoped to that specific event.

**Key difference from permanent attributes:** Event attributes are properties that change very often and are scoped for the life of the event. The next event has its own attributes.

**API — Disposition update (triggers an event):**

`PUT /v2/orgs/{orgId}/contact/{contactId}/disposition`

```json
{
    "stage": "INTERESTED",
    "disposition": "WARM",
    "call_time": "10:30",
    "payment_amount": "5000"
}
```

All fields beyond `stage` and `disposition` are accepted as additional event attributes. 

#### How Attributes and Events Work Together

Event triggers automation, attribute matcher matches / filters based on the attributes.

```
Permanent attributes (from lead profile)
    +
Event attributes (from the triggering event)
    =
Merged attributes → evaluated against matcher conditions
```

**If a key exists in both, the event attribute takes precedence.**

**Example:**

Lead has permanent attributes: `{ process: "RM", product_code: "P1" }`

A disposition event arrives with: `{ stage: "INTERESTED", disposition: "WARM" }`

The matcher evaluates against the merged set:

```
process = RM              (from permanent)
product_code = P1         (from permanent)
stage = INTERESTED        (from event)
disposition = WARM        (from event)
```

You can configure matcher conditions against any of these — e.g., trigger automation when `stage = INTERESTED` AND `process = RM`.