# 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`.


---

# 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/events-and-attributes.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.