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

name and workflows are required. Any experience document missing either property is invalid and will be rejected.

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.

Example

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

An empty string ("") is not a valid value for name. The minimum length is 1 character.

workflows

Type: array of Workflow 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.

Example

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

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.

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.

Example

{
  "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"
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

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).

Complete Example

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

Complete Experience Example

{
  "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"
          }
        }
      ]
    }
  ]
}

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