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


---

# 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://playbook.nativemsg.com/rcs-experience-schema/rcs-experience-schema/overview.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.