# Experience

The **Experience** object is the root of every nativeMsg experience document. It MUST be a valid JSON object conforming to JSON Schema draft-07.

## Properties

| Property                | Type                                                                                                 | Required | Default | Constraints                                | Description                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
| `name`                  | string                                                                                               | **Yes**  | —       | minLength: 1, maxLength: 100               | Human-readable name for this experience.                                          |
| `workflows`             | array of [Workflow](https://playbook.nativemsg.com/rcs-experience-schema/reference/broken-reference) | **Yes**  | —       | minItems: 1 (implied)                      | Ordered list of workflows defining the conversational logic.                      |
| `welcomeMessageExecute` | string                                                                                               | No       | —       | Must reference an existing workflow `name` | Name of the workflow to execute when the channel invitation message is displayed. |

{% hint style="danger" %}
`name` and `workflows` are required. Any experience document missing either property is invalid and will be rejected.
{% endhint %}

## Property Specifications

### `name`

**Type:** string\
**Required:** Yes\
**Constraints:** minLength: 1, maxLength: 100

The `name` property provides a human-readable identifier for the experience. It is used for display in the nativeMsg platform console and for logging. It does not need to be globally unique in the schema, but platform operators SHOULD treat it as a unique label within a project.

{% code title="Example" %}

```json
{
  "name": "Acme Retail Support — Spring 2025"
}
```

{% endcode %}

{% hint style="danger" %}
An empty string (`""`) is not a valid value for `name`. The minimum length is 1 character.
{% endhint %}

### `workflows`

**Type:** array of [Workflow](https://playbook.nativemsg.com/rcs-experience-schema/reference/broken-reference) objects\
**Required:** Yes

The `workflows` array defines every conversational flow available in this experience. Workflows are evaluated in document order for intent matching. The platform selects the first matching workflow.

{% code title="Example" %}

```json
{
  "name": "Order Status Bot",
  "workflows": [
    {
      "name": "check-order",
      "intents": ["check_order_status"],
      "actions": [
        {
          "send": {
            "message": {
              "text": "Please provide your order number."
            }
          }
        }
      ]
    }
  ]
}
```

{% endcode %}

{% hint style="info" %}
Workflow names within a single experience SHOULD be unique. The platform uses workflow names as targets for `execute`, `goto`, and `welcomeMessageExecute`. Duplicate names produce undefined resolution behavior.
{% endhint %}

### `welcomeMessageExecute`

**Type:** string\
**Required:** No

When set, `welcomeMessageExecute` names the workflow that the platform executes when it displays the channel invitation or welcome card to the user, before any user message is received. The value MUST match the `name` property of a workflow in the same experience.

{% code title="Example" %}

```json
{
  "name": "Customer Onboarding",
  "welcomeMessageExecute": "welcome",
  "workflows": [
    {
      "name": "welcome",
      "intents": ["nm:start"],
      "actions": [
        {
          "send": {
            "message": {
              "text": "Hi! I am your Acme assistant. Tap below to get started.",
              "quickReplies": [
                {
                  "type": "text",
                  "title": "Get started",
                  "payload": "get_started"
                }
              ]
            }
          }
        }
      ]
    }
  ]
}
```

{% endcode %}

{% hint style="warning" %}
If `welcomeMessageExecute` references a workflow name that does not exist in the `workflows` array, the welcome message step will fail silently or produce a platform error. Always verify the referenced name matches exactly (case-sensitive).
{% endhint %}

## Complete Example

The following is a complete, valid Experience document with two workflows.

{% code title="Complete Experience Example" %}

```json
{
  "name": "Acme Support Bot",
  "welcomeMessageExecute": "greeting",
  "workflows": [
    {
      "name": "greeting",
      "intents": ["greeting"],
      "expressions": [
        "hello",
        "hi",
        "hey",
        "good morning",
        "good afternoon"
      ],
      "actions": [
        {
          "name": "send-welcome",
          "send": {
            "message": {
              "text": "Welcome to Acme Support! What can I help you with?",
              "quickReplies": [
                {
                  "type": "text",
                  "title": "Order status",
                  "payload": "order_status"
                },
                {
                  "type": "text",
                  "title": "Returns",
                  "payload": "returns"
                },
                {
                  "type": "text",
                  "title": "Talk to an agent",
                  "payload": "human_agent"
                }
              ]
            }
          }
        }
      ]
    },
    {
      "name": "order-status",
      "intents": ["order_status", "check_order"],
      "expressions": [
        "where is my order",
        "track my package",
        "order status",
        "when will my order arrive"
      ],
      "actions": [
        {
          "name": "ask-order-number",
          "send": {
            "message": {
              "text": "Please enter your order number (e.g. ACM-12345)."
            }
          }
        },
        {
          "name": "capture-order-number",
          "waitFor": {
            "data": "text",
            "content": "orderNumber"
          }
        }
      ]
    }
  ]
}
```

{% endcode %}

## Validation Rules

The schema enforces the following validation rules at the root level:

| Rule                 | Constraint                     | Effect of violation     |
| -------------------- | ------------------------------ | ----------------------- |
| `name` present       | `required`                     | Schema validation error |
| `name` non-empty     | `minLength: 1`                 | Schema validation error |
| `name` within limit  | `maxLength: 100`               | Schema validation error |
| `workflows` present  | `required`                     | Schema validation error |
| `workflows` is array | `type: array`                  | Schema validation error |
| Each workflow item   | `$ref: #/definitions/Workflow` | Schema validation error |