> This page is for API Reference & Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Conversational Processes

> Create, read and update conversational processes through the Moveworks Configuration API.

`platform.extensions.conversational-processes`

A conversational process is the user-facing flow of a plugin: the slots it collects from the user and the steps it runs, such as actions, branches and replies.

To learn what conversational processes do, see [Conversational Processes](/tool-studio/conversation-process) in the Tool Studio docs.

* **Endpoint:** `/platform/extensions/conversational-processes`  |  **Methods:** GET, PATCH, POST
* **Request shape:** fields go at the top level of the JSON body, with no `resource` wrapper. The item's `id` goes in the URL for reads and updates, not in the body.
* **Updates:** a JSON merge-patch with `version: {num, change_description}` from your last read. Lists of objects merge row by row, so read first and send the whole list when you remove or reorder rows. See [Tool Studio](/api-reference/configuration-api/tool-studio/overview#how-updates-work).
* **References:** Activities call actions by `id` (`action_id.http_action`, `compound_action` or `script_action`). Slots of a custom type use the data type's `name`. A plugin launches the process through `execution_config.conversational_plugin_body_config_uuid`, which takes the process's `id`.

### Endpoints

All paths are relative to `https://api.moveworks.ai/configurations/v1alpha1`. Each endpoint page lists the request and response schema, an example, and the errors it can return.

| Method  | Path                                                 | Endpoint reference                                                                                                                   |
| ------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `GET`   | `/platform/extensions/conversational-processes`      | [List conversational processes](/api-reference/configuration-api/tool-studio/conversational-processes/list-conversational-processes) |
| `POST`  | `/platform/extensions/conversational-processes`      | [Create conversational process](/api-reference/configuration-api/tool-studio/conversational-processes/create-conversational-process) |
| `GET`   | `/platform/extensions/conversational-processes/{id}` | [Get conversational process](/api-reference/configuration-api/tool-studio/conversational-processes/get-conversational-process)       |
| `PATCH` | `/platform/extensions/conversational-processes/{id}` | [Update conversational process](/api-reference/configuration-api/tool-studio/conversational-processes/update-conversational-process) |

### Rules the API checks

* The server sets `signature.name` from `signature.display_name`. Don't send it.
* `conversation_flow` is one block: `sequential`, `switch`, `activity`, `return` or `noop`. Don't put a `sequential` block directly inside another `sequential` block.
* A `switch` case can't have an empty `then`; use `noop`.
* `text` activity templates use Mustache over `data`, for example `{{ data.purchase_order.status }}`.

### Fields

| Field               | Type                              | Required  | Notes                                                                                                             |
| ------------------- | --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `id`                | string                            | read-only | Unique identifier of the conversational process, assigned by the server. Cannot be changed.                       |
| `signature`         | FunctionSignatureSettings         | ✅         | Name and description of the conversational process. The internal name is derived from the display name. Required. |
| `slots`             | array\<ConversationalProcessSlot> |           | Input values (slots) the process collects from the user and uses as variables in the conversation flow.           |
| `conversation_flow` | ConversationBlock                 | ✅         | The control flow of the process, built from sequential, switch, activity, return and no-op blocks. Required.      |
| `updated_time`      | string                            | read-only | When the configuration was last updated.                                                                          |
| `updated_by`        | string                            | read-only | Who last updated the configuration.                                                                               |
| `version`           | Version                           | ✅         | Document version. On update, send back the num from your last read.                                               |

### Example create body

```json
{
  "signature": {
    "display_name": "Purchase Order Lookup",
    "description": "Looks up a purchase order by number and reports its status.",
    "name": "example"
  },
  "slots": [
    {
      "name": "po_number",
      "description": "The purchase order number the user is asking about.",
      "type": {
        "primitive": "string"
      },
      "resolution": {
        "must_request": true,
        "value_population_policy": {
          "inference_type": "CONVERSATIONAL_PROCESS_INFERENCE_TYPE_ALWAYS_INFER"
        }
      }
    }
  ],
  "conversation_flow": {
    "sequential": {
      "steps": [
        {
          "activity": {
            "prerequisite_slots": [
              "po_number"
            ],
            "output_slot": "purchase_order",
            "action": {
              "action_id": {
                "http_action": "1b7d4f5a-2c88-4e0b-9f31-7c5a0d9e4411"
              },
              "input_mapper": {
                "po_number": "data.po_number"
              }
            },
            "needs_confirmation": false
          }
        },
        {
          "return": {}
        }
      ]
    }
  },
  "version": {
    "change_description": "Initial version."
  }
}
```