# Core Concepts

This section provides normative definitions for every core term used throughout this documentation. Terms defined here are used consistently without re-explanation in subsequent sections.

## Definitions

### Experience

An **Experience** is the root configuration object that defines a complete nativeMsg conversational agent. An experience MUST have a unique `name` and MUST contain at least one [Workflow](#workflow). It is the unit of deployment: the entire object is submitted to the nativeMsg platform as a single JSON document.

### Workflow

A **Workflow** is a named unit of conversational logic that is activated when the platform determines that an incoming user message matches one of its [Intents](#intent), a button is pressed or a quick reply response. A workflow contains an ordered list of [Actions](#action) that are executed sequentially when the workflow is triggered. A workflow MAY also define [Keywords](#keyword), [Expressions](#expression), and a [Validation](#validation) constraint.

### Intent

An **Intent** represents the meaning or purpose of a user's message. An intent is identified by name. When a user sends a message, the platform evaluates all workflows and selects the one whose intent name, keyword, or expression best matches the message content. An intent MAY be specified as a bare string (the intent name) or as an [IntentObject](#intentobject) with additional configuration.

### IntentObject

An **IntentObject** is the structured form of an intent declaration within a workflow. It extends a bare string intent with optional [Expressions](#expression). 

### Keyword

A **Keyword** is a named set of literal string values that trigger a workflow when the user's message matches any of the listed values. Keywords are evaluated before NLU expression matching. A keyword MAY include alternate expression phrasings for each value to improve recognition.

### Expression

An **Expression** is a natural language training phrase that teaches the NLU engine which utterances should match a given intent. An expression MAY be specified as a bare string or as a structured object with `text`, an optional `generate` flag, and an optional list of [Slots](#slot).

### Slot

A **Slot** is a named entity extracted from an expression. It identifies a typed sub-phrase within an expression text that the NLU engine should recognize and extract as a variable. Slots are used to capture entities such as product names, dates, or locations from free-text input.

### Action

An **Action** is a single executable step within a workflow. Actions are evaluated in order. An action MAY include a `conditions` array; if conditions are present and not satisfied, the action is skipped. An action executes exactly one primary operation, determined by which action-type property is present: `send`, `waitFor`, `delay`, `execute`, `goto`, `assignTags`, `assignAttributes`, `updateAttribute`, `subscribe`, `updateSettings`, or `pause`.

### Attribute

An **Attribute** is a named variable associated with a conversation or contact. Attributes are set by `assignAttributes`, `updateAttribute`, or `waitFor` actions, and read back using `{attributeName}` placeholder syntax in message text, request URLs, and other string fields. Attribute names MUST match the pattern `^[a-zA-Z][a-zA-Z0-9_]*$`. Nested attribute paths use dot notation and MUST match `^[a-zA-Z][a-zA-Z0-9_.]*$`.

### Condition

A **Condition** is a predicate evaluated at runtime to determine whether an action should execute. Conditions MAY test channel type, channel ID, assigned tags, device type, device platform, or attribute values via `comparisons`. Multiple conditions in an action's `conditions` array are combined using [Operator](#operator) objects.

### Operator

An **Operator** is a logical combinator (`AND`, `OR`, `NOT`) inserted into a `conditions` array to compose multiple [Condition](#condition) objects. Operators apply to the conditions that follow them according to standard boolean semantics.

### Validation

A **Validation** is a constraint attached to a workflow or action that tests a named attribute value against a regular expression pattern. If the pattern does not match, execution is redirected to the workflow or action named in `executeOnError`.

### Channel

A **Channel** is the messaging medium through which the user communicates (for example: RCS, DSC, DLC). Channel type is available as a condition filter and as a channel restriction on individual actions via the `channel` property.

### SendAction

A **SendAction** is the value of an action's `send` property. It specifies what to deliver to the user or to an external system. Exactly one of its sub-properties SHOULD be present: `message`, `email`, `request`, `json`, `note`, `rss`, or `populate`.

## Message Flow

The following diagram shows how an incoming user message is processed from receipt through workflow execution.

```mermaid
flowchart TD
    A([User sends message]) --> B{Keyword match?}
    B -- Yes --> E[Select matching Workflow]
    B -- No --> C{Intent / NLU match?}
    C -- Yes --> E
    C -- No --> D[Default / fallback Workflow]
    D --> E
    E --> F[Evaluate Workflow Validation]
    F -- Fails --> G[Execute executeOnError target]
    F -- Passes --> H[Begin Action sequence]
    H --> I{Action has conditions?}
    I -- No --> J[Execute Action]
    I -- Yes --> K{Conditions satisfied?}
    K -- No --> L[Skip Action]
    K -- Yes --> J
    J --> M{More actions?}
    L --> M
    M -- Yes --> I
    M -- No --> N([Workflow complete])
    G --> N
```

{% hint style="info" %}
Keyword matching is evaluated before NLU intent matching. If a message matches a keyword exactly, the NLU step is bypassed for that turn.
{% endhint %}

## Placeholder Syntax

Many string fields in the schema support attribute placeholder substitution. The platform replaces `{attributeName}` tokens at runtime with the current value of the named attribute. Nested paths use dot notation: `{order.trackingNumber}`.

Placeholders are supported in: message `text`, request `url`, request `content`, note `text`, email `subject`, email `text`, and `recipientPhone`.

## Reserved Prefix

Workflow names and action names MUST NOT begin with the prefix `nm:`. This prefix is reserved for internal nativeMsg system workflows and actions.