# Actions An **Action** is a single executable step within a workflow. Actions are processed sequentially. If an action includes a `conditions` array, the platform evaluates those conditions first; if they are not satisfied, the action is skipped and execution continues with the next action. ## Action Properties | Property | Type | Required | Default | Constraints | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------ | ---------------------------------------------------------------------------- | | `name` | string | No | — | Must not start with `nm:` | Unique identifier for this action. Used as a target by `execute` and `goto`. | | `conditions` | array of [Condition](broken://pages/5ec5e72928181d14c580c94fff1c5c7de67c8f86) \| [Operator](broken://pages/5ec5e72928181d14c580c94fff1c5c7de67c8f86#operator) | No | — | — | Predicates controlling whether this action executes. | | `validation` | [Validation](broken://pages/d1da14ba55d42ff713017b758d2ac856535a6698#validation) | No | — | — | Attribute validation applied before this action executes. | | `channel` | string | No | — | e.g. `"rcs"`, `"dsc"`, `"dlc"` | Restricts this action to a specific channel type. | | `send` | [SendAction](#sendaction) | No | — | — | Delivers a message, email, HTTP request, note, RSS feed, or data population. | | `waitFor` | [WaitForAction](#waitforaction) | No | — | — | Pauses execution to collect user input. | | `delay` | [DelayAction](#delayaction) | No | — | — | Pauses execution for a fixed duration. | | `execute` | string \| array of string | No | — | — | Executes one or more named workflows or actions. | | `goto` | string | No | — | — | Transfers execution to a named workflow or action. | | `assignTags` | string \| array of string | No | — | — | Assigns one or more tags to the conversation. | | `assignAttributes` | [AssignAttributesAction](#assignattributesaction) | No | — | — | Assigns or updates named attributes. | | `updateAttribute` | [UpdateAttributeAction](#updateattributeaction) | No | — | — | Updates a single attribute with transformation options. | | `subscribe` | boolean | No | — | — | Subscribes the contact to the current channel when `true`. | | `updateSettings` | [UpdateSettingsAction](#updatesettingsaction) | No | — | — | Updates experience or conversation settings at runtime. | | `pause` | [PauseAction](#pauseaction) | No | — | — | Inserts a short pause (typing indicator) before the next action. | {% hint style="info" %} An action with no primary operation property (no `send`, `waitFor`, `delay`, etc.) is valid — it can exist solely for its `conditions`, `assignTags`, or `assignAttributes` side effects. {% endhint %} ## SendAction The `send` property delivers content to the user or an external system. At most one sub-property SHOULD be populated per `send` object. | Property | Type | Required | Description | | ---------- | ------------------------------------------------------------------ | -------- | ---------------------------------------- | | `message` | [Message](broken://pages/a96939910c71ba9feedfb956bba3dc3d8c39ad65) | No | Sends a message to the user. | | `email` | [EmailAction](#emailaction) | No | Sends an email. | | `request` | [RequestAction](#requestaction) | No | Sends an HTTP request. | | `json` | object \| array | No | Sends a raw JSON payload. | | `note` | [NoteAction](#noteaction) | No | Sends an internal note. | | `rss` | [RssAction](#rssaction) | No | Fetches and renders an RSS feed. | | `populate` | [PopulateData](#populatedata) | No | Populates attributes from a data source. | ### EmailAction Sends an email from within a workflow. | Property | Type | Required | Default | Constraints | Description | | --------- | ------------------------- | -------- | ------- | ----------------------- | ---------------------------------------------------- | | `to` | string \| array of string | **Yes** | — | Valid email address(es) | Recipient address(es). | | `cc` | string \| array of string | No | — | Valid email address(es) | CC recipient(s). | | `bcc` | string \| array of string | No | — | Valid email address(es) | BCC recipient(s). | | `subject` | string | No | — | — | Email subject line. Supports attribute placeholders. | | `text` | string | No | — | — | Email body. Supports attribute placeholders. | | `isHtml` | boolean | No | `false` | — | When `true`, the `text` body is rendered as HTML. | {% code title="email-action.json" %} ```json { "send": { "email": { "to": "support-team@acme.com", "cc": "manager@acme.com", "subject": "New support request from {contactName}", "text": "Contact: {contactName}\nPhone: {contactPhone}\nIssue: {issueDescription}", "isHtml": false } } } ``` {% endcode %} ### RequestAction Sends an HTTP request and optionally maps the response into attributes. | Property | Type | Required | Default | Constraints | Description | | ----------------- | ---------------- | ----------- | -------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `url` | string | **Yes** | — | Must be a valid URL or `{attribute}` placeholder | Request URL. Supports attribute placeholders. | | `method` | string | No | `"GET"` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | HTTP method. | | `dataFormat` | string | No | `"text"` | `text`, `json`, `form` | Request body format. | | `headers` | object | No | — | Map of string → string | HTTP request headers. | | `content` | string \| object | Conditional | — | Required when method is `POST`, `PUT`, or `PATCH` | Request body. | | `response` | string \| object | No | — | — | Attribute name or mapping object for storing the response body. | | `responseHeaders` | string \| object | No | — | — | Attribute name or mapping for storing response headers. | | `retries` | integer | No | `0` | minimum: 0 | Number of retry attempts on failure. | | `fallback` | string | No | — | — | Workflow or action to execute on request failure. | | `process` | boolean | No | `true` | — | When `true`, attribute placeholders in `content` are substituted before sending. | | `async` | boolean | No | `false` | — | When `true`, the request is sent asynchronously and execution continues without waiting. | | `allowHtml` | boolean | No | `false` | — | When `true`, HTML in the response is not sanitized. | {% hint style="danger" %} `content` is required when `method` is `POST`, `PUT`, or `PATCH`. Omitting it when using these methods produces a validation error. {% endhint %} {% hint style="danger" %} When `dataFormat` is `"json"` and `method` is `POST`, `PUT`, or `PATCH`, the `content` field MUST be a JSON object or a string beginning with `{`. {% endhint %} {% code title="request-action-get.json" %} ```json { "send": { "request": { "url": "https://api.acme.com/v1/orders/{orderNumber}", "method": "GET", "headers": { "Authorization": "Bearer {apiToken}", "Accept": "application/json" }, "dataFormat": "json", "response": { "status": "orderStatus", "estimatedDelivery": "deliveryDate" }, "retries": 2, "fallback": "api-error-handler" } } } ``` {% endcode %} POST example: {% code title="request-action-post.json" %} ```json { "send": { "request": { "url": "https://api.acme.com/v1/leads", "method": "POST", "dataFormat": "json", "headers": { "Content-Type": "application/json", "Authorization": "Bearer {apiToken}" }, "content": { "name": "{contactName}", "phone": "{contactPhone}", "source": "rcs_chat" }, "response": "leadId", "retries": 1, "fallback": "lead-creation-failed" } } } ``` {% endcode %} ### NoteAction Sends an internal note (not visible to the end user). | Property | Type | Required | Default | Constraints | Description | | ---------------- | ------------------------- | -------- | ------- | ----------- | --------------------------------------------------------------- | | `text` | string | **Yes** | — | — | Note content. Supports attribute placeholders. | | `channelId` | integer \| null | No | — | — | Target channel ID for the note. | | `recipientPhone` | string \| null | No | — | — | Phone number of the recipient. Supports attribute placeholders. | | `executeOnError` | string \| array of string | No | — | — | Workflow or action to execute on error. | {% code title="note-action.json" %} ```json { "send": { "note": { "text": "Customer {contactName} requested a refund for order {orderNumber}. Escalation required.", "channelId": 42 } } } ``` {% endcode %} ### RSSAction Fetches an RSS feed and renders it as a carousel or list. | Property | Type | Required | Default | Constraints | Description | | ---------------- | ------ | -------- | ------------ | ---------------------- | --------------------------- | | `url` | string | **Yes** | — | format: uri | URL of the RSS feed. | | `preferedLayout` | string | No | `"carousel"` | `"list"`, `"carousel"` | Preferred rendering layout. | {% code title="rss-action.json" %} ```json { "send": { "rss": { "url": "https://blog.acme.com/feed.xml", "preferedLayout": "carousel" } } } ``` {% endcode %} ### PopulateData Populates attributes from a data source. | Property | Type | Required | Default | Constraints | Description | | ---------------------- | --------------- | -------- | ------- | ----------- | --------------------------------------------- | | `from` | string \| null | No | — | — | Source attribute name. | | `attribute` | string \| null | No | — | — | Target attribute name. | | `allowInnerAttributes` | boolean \| null | No | `true` | — | Whether to allow nested attribute resolution. | {% code title="populate-data.json" %} ```json { "send": { "populate": { "from": "apiResponseData", "attribute": "productList", "allowInnerAttributes": true } } } ``` {% endcode %} ## WaitForAction Pauses workflow execution until the user provides input of the specified type. | Property | Type | Required | Default | Constraints | Description | | ------------------ | ------------------------- | -------- | ------- | ---------------------------------- | --------------------------------------------------------- | | `data` | string \| array of string | **Yes** | — | See enum values | Type(s) of data to accept from the user. | | `content` | string | **Yes** | — | Pattern: `^[a-zA-Z][a-zA-Z0-9_]*$` | Attribute name in which to store the received input. | | `keywords` | array of KeywordCapture | No | — | — | Keyword-to-attribute mappings recognized during the wait. | | `executeOnError` | string \| array of string | No | — | — | Target(s) to execute when input fails validation. | | `executeOnTimeout` | string \| array of string | No | — | — | Target(s) to execute when the wait times out. | | `timeout` | string | No | — | e.g. `"30s"`, `"5m"`, `"1h"` | Duration after which the timeout handler fires. | **Accepted `data` values:** | Value | Description | | ---------------- | ------------------------------- | | `"message"` | Any message, including media | | `"text"` | Plain text input | | `"quick reply"` | Quick reply selection | | `"multi select"` | Multiple quick reply selections | | `"number"` | Numeric input | | `"money"` | Monetary amount | | `"distance"` | Distance measurement | | `"coordinates"` | Geographic coordinates | | `"datetime"` | Date and/or time | | `"file"` | File attachment | {% hint style="danger" %} Both `data` and `content` are required in a `waitFor` object. The `content` value MUST match the pattern `^[a-zA-Z][a-zA-Z0-9_]*$`. {% endhint %} KeywordCapture sub-object: | Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------------------------------------------ | | `name` | string | **Yes** | Keyword name to watch for. | | `attribute` | string | **Yes** | Attribute in which to store the matched keyword value. | {% code title="waitfor-action.json" %} ```json { "waitFor": { "data": "text", "content": "userEmail", "timeout": "5m", "executeOnTimeout": "email-capture-timeout", "executeOnError": "invalid-email-format" } } ``` {% endcode %} ## DelayAction Pauses execution for a fixed amount of time, with optional timeout routing. | Property | Type | Required | Default | Constraints | Description | | ------------------ | ------------------------- | -------- | ------- | ----------- | ------------------------------------- | | `seconds` | integer | No | — | minimum: 0 | Delay duration in seconds. | | `milliseconds` | integer | No | — | minimum: 0 | Delay duration in milliseconds. | | `executeOnTimeout` | string \| array of string | No | — | — | Target(s) to execute after the delay. | | `timeout` | string | No | — | — | Alternative timeout duration string. | {% code title="delay-action.json" %} ```json { "delay": { "seconds": 3 } } ``` {% endcode %} ## Execute Executes one or more named workflows or actions by name. Use `execute` when you want to run a sub-workflow and then continue in the current workflow. Contrast with `goto`, which does not return. | Form | Type | Description | | ---------------- | --------------- | -------------------------------------- | | Single target | string | Executes the named workflow or action. | | Multiple targets | array of string | Executes each named target in order. | {% code title="execute-single.json" %} ```json { "execute": "send-confirmation-message" } ``` {% endcode %} {% code title="execute-multiple.json" %} ```json { "execute": ["log-event", "send-confirmation-message", "notify-agent"] } ``` {% endcode %} ## Goto Transfers execution to a named workflow or action. Unlike `execute`, `goto` does not return to the current workflow after the target completes. {% code title="goto.json" %} ```json { "goto": "main-menu" } ``` {% endcode %} ## AssignTags Assigns one or more tags to the conversation. | Form | Type | Description | | ------------- | --------------- | ----------------------- | | Single tag | string | Assigns the named tag. | | Multiple tags | array of string | Assigns each named tag. | {% code title="assign-tags.json" %} ```json { "assignTags": ["vip-customer", "order-inquiry"] } ``` {% endcode %} ## AssignAttributesAction Assigns or updates multiple attributes in a single action. | Property | Type | Required | Default | Constraints | Description | | ------------------------ | ------------------------------------------------- | -------- | ------- | ----------- | --------------------------------------------------------------------- | | `attributes` | array of [AttributeValue](#attributevalue) | **Yes** | — | — | List of attribute assignments. | | `value` | string \| object \| array \| null | No | — | — | Default value applied when an `AttributeValue` has no explicit value. | | `replace` | string \| null | No | — | — | Regex pattern for string replacement. | | `process` | boolean \| null | No | `true` | — | When `true`, attribute placeholders in values are substituted. | | `evaluate` | boolean \| null | No | `false` | — | When `true`, values are evaluated as expressions. | | `embeddingMode` | boolean \| null | No | `false` | — | Enables embedding mode for AI vector operations. | | `takeNext` | boolean \| null | No | `false` | — | Extracts the next value in a sequence. | | `takeNextPath` | string \| null | No | — | — | JSON path for `takeNext` extraction. | | `multipleValues` | `"array"` \| `"object"` \| null | No | — | — | How to store multiple values. | | `multipleValuesSettings` | [MultipleValuesSettings](#multiplevaluessettings) | No | — | — | Configuration for multi-value storage. | | `format` | string \| null | No | — | — | Format string applied to values. | | `remove` | boolean \| null | No | `false` | — | When `true`, removes the attribute instead of setting it. | ### AttributeValue | Property | Type | Required | Default | Constraints | Description | | ------------------------ | ------------------------------------------------- | -------- | ------- | ----------------------------------- | ---------------------------------------- | | `attributePath` | string | **Yes** | — | Pattern: `^[a-zA-Z][a-zA-Z0-9_.]*$` | Dot-notation path to the attribute. | | `value` | string \| object \| array \| null | No | — | — | Value to assign. | | `replace` | string \| null | No | — | — | Regex pattern for string replacement. | | `process` | boolean \| null | No | — | — | Attribute placeholder substitution flag. | | `evaluate` | boolean \| null | No | — | — | Expression evaluation flag. | | `embeddingMode` | boolean \| null | No | — | — | Embedding mode flag. | | `takeNext` | boolean \| null | No | — | — | Extract next value in sequence. | | `takeNextPath` | string \| null | No | — | — | JSON path for `takeNext`. | | `format` | string \| null | No | — | — | Format string. | | `multipleValues` | `"array"` \| `"object"` \| null | No | — | — | Multi-value storage mode. | | `multipleValuesSettings` | [MultipleValuesSettings](#multiplevaluessettings) | No | — | — | Multi-value configuration. | | `remove` | boolean \| null | No | — | — | Remove flag. | {% hint style="danger" %} `attributePath` MUST match the pattern `^[a-zA-Z][a-zA-Z0-9_.]*$`. Paths starting with a digit or containing special characters (other than `.` and `_`) are invalid. {% endhint %} {% code title="assign-attributes.json" %} ```json { "assignAttributes": { "attributes": [ { "attributePath": "contactName", "value": "{firstName} {lastName}", "process": true }, { "attributePath": "order.status", "value": "pending" }, { "attributePath": "sessionTimestamp", "value": "{currentTimestamp}", "process": true } ] } } ``` {% endcode %} ### MultipleValuesSettings | Property | Type | Required | Default | Constraints | Description | | ----------------------- | ------- | -------- | ------- | ---------------------- | ------------------------------------------------------------- | | `singleValueStandalone` | boolean | No | `true` | — | When `true`, a single value is stored directly (not wrapped). | | `delimiter` | string | No | — | — | Delimiter for joining multiple values. | | `prefix` | string | No | — | — | Prefix prepended to each value. | | `suffix` | string | No | — | — | Suffix appended to each value. | | `rootElement` | string | No | — | — | XML/JSON root element name. | | `valueElement` | string | No | — | — | XML/JSON value element name. | | `xmlOptions` | object | No | — | Map of string → string | Additional XML serialization options. | ## UpdateAttributeAction Updates a single attribute. Similar to `AssignAttributesAction` but scoped to one attribute. | Property | Type | Required | Default | Constraints | Description | | ----------- | ------------------------- | -------- | ------- | ----------- | ------------------------------------- | | `attribute` | string \| array of string | **Yes** | — | — | Attribute name(s) to update. | | `value` | string \| object \| array | No | — | — | Value to assign. | | `replace` | string | No | — | — | Regex pattern for string replacement. | | `process` | boolean | No | `true` | — | Attribute placeholder substitution. | | `evaluate` | boolean | No | `false` | — | Expression evaluation. | | `takeNext` | boolean | No | `false` | — | Extract next value in sequence. | {% hint style="danger" %} `attribute` is required. An `updateAttribute` object with no `attribute` property is invalid. {% endhint %} {% code title="update-attribute.json" %} ```json { "updateAttribute": { "attribute": "orderStatus", "value": "confirmed", "process": false } } ``` {% endcode %} ## Subscribe When set to `true`, subscribes the current contact to the channel. {% code title="subscribe.json" %} ```json { "subscribe": true } ``` {% endcode %} ## UpdateSettingsAction Updates experience or conversation settings at runtime. | Property | Type | Required | Description | | ----------------------- | ---------------------- | -------- | --------------------------------------- | | `rcsExperience` | object | No | RCS experience settings. | | `rcsExperience.enabled` | boolean | No | Enables or disables the RCS experience. | | `conversation` | object | No | Conversation-level settings. | | `conversation.priority` | `"normal"` \| `"high"` | No | Sets the conversation priority. | {% code title="update-settings-priority.json" %} ```json { "updateSettings": { "conversation": { "priority": "high" } } } ``` {% endcode %} {% code title="update-settings-rcs.json" %} ```json { "updateSettings": { "rcsExperience": { "enabled": false } } } ``` {% endcode %} ## PauseAction Inserts a brief pause before the next action, typically displayed as a typing indicator. | Property | Type | Required | Default | Constraints | Description | | -------------- | ------- | -------- | ------- | ----------- | ------------------------------- | | `seconds` | integer | No | — | minimum: 0 | Pause duration in seconds. | | `milliseconds` | integer | No | — | minimum: 0 | Pause duration in milliseconds. | {% code title="pause-action.json" %} ```json { "pause": { "milliseconds": 800 } } ``` {% endcode %} ## Complete Action Sequence Example The following shows a realistic action sequence that collects user input, calls an API, and branches based on the response. {% code title="complete-action-sequence.json" %} ```json [ { "name": "prompt-for-email", "send": { "message": { "text": "Please enter your email address to look up your account." } } }, { "name": "capture-email", "waitFor": { "data": "text", "content": "userEmail", "timeout": "3m", "executeOnTimeout": "email-timeout-handler" } }, { "name": "pause-before-lookup", "pause": { "milliseconds": 500 } }, { "name": "lookup-account", "send": { "request": { "url": "https://api.acme.com/v1/accounts/lookup", "method": "POST", "dataFormat": "json", "headers": { "Authorization": "Bearer {apiToken}", "Content-Type": "application/json" }, "content": { "email": "{userEmail}" }, "response": { "accountId": "accountId", "tier": "accountTier", "found": "accountFound" }, "retries": 1, "fallback": "api-error" } } }, { "name": "check-account-found", "conditions": [ { "comparisons": [ ["accountFound", "==", "false"] ] } ], "goto": "account-not-found" }, { "name": "send-account-summary", "send": { "message": { "text": "Found your account! You are on the {accountTier} plan. Account ID: {accountId}.", "quickReplies": [ { "type": "text", "title": "View billing", "payload": "view_billing" }, { "type": "text", "title": "Upgrade plan", "payload": "upgrade_plan" } ] } } }, { "name": "tag-account-tier", "assignTags": "{accountTier}" } ] ``` {% endcode %} --- # 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/reference/actions.md?ask= ``` 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.