# Overview

The RCS Experience Schema is a JSON Schema (draft-07) specification that defines the complete structure of an RCS conversational experience. An experience describes how a messaging agent responds to user input: which workflows are triggered by which intents, what messages are sent, how user data is captured, and how the conversation branches based on conditions.

## Scope

**This specification covers:**

* The root Experience object and its required properties
* Workflow definition, intent matching, keyword recognition, and expression configuration
* All Action types: message sending, HTTP requests, user-input capture, flow control, attribute assignment, and settings updates
* Message variants: text, media, buttons, quick replies, carousels, lists, and rich cards
* Condition and Operator structures for conditional action execution
* Channel-specific constraints and compatibility rules

**This specification does not cover:**

* Authentication or authorization for the nativeMsg API
* How experiences are deployed or published to a channel
* Webhook configuration or inbound event formats
* AI model configuration or NLU training pipelines
* Analytics, reporting, or conversation history APIs

## Normative Language

{% hint style="info" %}
This documentation uses RFC 2119 terminology throughout all normative sections.
{% endhint %}

| Keyword        | Meaning                                                       |
| -------------- | ------------------------------------------------------------- |
| **MUST**       | Absolute requirement. Violations produce invalid experiences. |
| **MUST NOT**   | Absolute prohibition. Violations produce invalid experiences. |
| **SHOULD**     | Recommended. Non-conformance requires justification.          |
| **SHOULD NOT** | Not recommended. Non-conformance requires justification.      |
| **MAY**        | Optional. Permitted but not required.                         |

Normative requirements derive directly from the JSON Schema definition. Informative notes, tips, and implementation guidance are marked with

blocks.

## What You Can Build

An experience built with this schema can:

* **Route conversations** — Match user messages to workflows by intent name, keyword, or natural language expression
* **Send rich messages** — Plain text, images, videos, interactive buttons, quick replies, carousels, lists, and RCS rich cards
* **Capture user input** — Collect text, numbers, dates, locations, and files and store them as named attributes
* **Call external APIs** — Make HTTP requests during a conversation and map response data into attributes
* **Branch conditionally** — Execute different actions based on attribute values, channel type, tags, and device platform
* **Assign metadata** — Tag conversations, set attributes, and update experience settings at runtime
* **Send notifications** — Dispatch internal notes or emails as part of a workflow

## Documentation Organization

| Section                                                                                                                  | Contents                                                           |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| [Quick Start](https://playbook.nativemsg.com/rcs-experience-schema/rcs-experience-schema/quick-start)                    | Minimal working example, field annotations, and schema validation  |
| [Core Concepts](https://playbook.nativemsg.com/rcs-experience-schema/rcs-experience-schema/core-concepts)                | Normative definitions of all core terms and a message-flow diagram |
| [Reference: Experience](https://playbook.nativemsg.com/rcs-experience-schema/reference/experience)                       | Root object specification                                          |
| [Reference: Workflow](https://playbook.nativemsg.com/rcs-experience-schema/reference/workflow)                           | Workflow, Intent, Keyword, Expression specifications               |
| [Reference: Actions](https://playbook.nativemsg.com/rcs-experience-schema/reference/actions)                             | All action types with complete property tables                     |
| [Reference: Messages](https://playbook.nativemsg.com/rcs-experience-schema/reference/messages)                           | Message variants, buttons, quick replies, carousels, rich cards    |
| [Reference: Conditions](https://playbook.nativemsg.com/rcs-experience-schema/reference/conditions)                       | Condition, Operator, and comparison semantics                      |
| [Guides: Coding Language Examples](https://playbook.nativemsg.com/rcs-experience-schema/guides/coding-language-examples) | Validate and deploy an experience in 7  programming languages      |
| [Guides: Common Patterns](https://playbook.nativemsg.com/rcs-experience-schema/guides/common-patterns)                   | Implementation cookbook: 8 complete recipes                        |
| [Troubleshooting](https://playbook.nativemsg.com/rcs-experience-schema/guides/troubleshooting)                           | Validation error reference and debugging checklist                 |

## Schema Identity

| Field                    | Value                                                                 |
| ------------------------ | --------------------------------------------------------------------- |
| `$schema`                | `http://json-schema.org/draft-07/schema#`                             |
| `$id`                    | `https://docs.nativemsg.com/schemas/rcs-experience-schema-1-0-0.json` |
| Root type                | `object`                                                              |
| Required root properties | `name`, `workflows`                                                   |

## Minimal Valid Experience

The following is the smallest syntactically valid experience. It contains one workflow, one intent, and one action that sends a text message.

{% code title="minimal-experience.json" %}

```json
{
  "name": "Hello World Experience",
  "workflows": [
    {
      "intents": ["greeting"],
      "actions": [
        {
          "send": {
            "message": {
              "text": "Hello! How can I help you today?"
            }
          }
        }
      ]
    }
  ]
}
```

{% endcode %}

For a fully annotated version of this example, see [Quick Start](https://playbook.nativemsg.com/rcs-experience-schema/rcs-experience-schema/quick-start).