# Workflow Types

Hexabot supports conversational, scheduled, and manual workflows. The type is selected when a workflow is created and controls trigger behavior, input schema editability, test panel behavior, and action availability.

<figure><img src="/files/4m5jmyKIQoOMEdRnwVQ2" alt=""><figcaption></figcaption></figure>

Conversational workflows are triggered by chat events. Scheduled workflows run from a cron schedule. Manual workflows run from the API or admin UI with an author-defined input schema.

### Type Summary

| Type           | Trigger                                    | Input schema                                       | Schema editability | Editor test panel     |
| -------------- | ------------------------------------------ | -------------------------------------------------- | ------------------ | --------------------- |
| Conversational | Incoming channel messages and chat events. | Fixed system schema with message data.             | Read-only.         | Embedded chat tester. |
| Scheduled      | The workflow's cron schedule.              | Fixed system schema with schedule metadata.        | Read-only.         | Trigger simulator.    |
| Manual         | API call or manual run from the admin UI.  | Custom JSON Schema created by the workflow author. | Editable.          | Trigger simulator.    |

The workflow type cannot be changed after the workflow is created. If you need a different trigger model, create a new workflow with the correct type.

### Conversational Workflows

Use conversational workflows for bot conversations, channel-driven automation, handover flows, and responses to incoming messages.

The input schema is generated by Hexabot and cannot be edited. It describes the message event that triggered the run.

| Field          | Type           | Required | Description                                                                                                 |
| -------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `message_type` | `string`       | No       | Type of inbound message associated with the triggering event.                                               |
| `payload`      | Any JSON value | No       | Raw event payload passed to the workflow. The shape depends on the source channel.                          |
| `message`      | `object`       | Yes      | Full message object received from the channel. Additional nested properties are allowed inside this object. |
| `text`         | `string`       | Yes      | Extracted text content from the inbound message.                                                            |
| `mid`          | `string`       | No       | Unique identifier of the inbound message.                                                                   |

The conversational input object does not accept arbitrary top-level fields. Workflow expressions usually read from `$input.text`, `$input.message`, `$input.payload`, or runtime context in `$context`.

Example:

```yaml
defs:
  reply:
    kind: task
    action: send_text_message
    inputs:
      text: "='You said: ' & $input.text"

flow:
  - do: reply
```

### Scheduled Workflows

Use scheduled workflows for recurring jobs such as daily summaries, periodic syncs, reminders, cleanup tasks, or scheduled notifications.

The input schema is generated by Hexabot and cannot be edited. It describes the schedule event that triggered the run.

| Field          | Type               | Required | Description                                                                                |
| -------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------ |
| `schedule`     | `string` or `null` | Yes      | Schedule expression that triggered this workflow run.                                      |
| `triggered_at` | `string` or `null` | Yes      | Date and time when the workflow run was triggered. When present, it is a date-time string. |

The scheduled input object does not accept arbitrary top-level fields. Use `$input.schedule` and `$input.triggered_at` when a step needs to know why or when the run started.

Example:

```yaml
defs:
  call_report_api:
    kind: task
    action: http_request
    inputs:
      method: POST
      url: https://example.com/reports/daily
      body:
        triggered_at: "=$input.triggered_at"

flow:
  - do: call_report_api
```

### Manual Workflows

Use manual workflows for reusable automations that should run on demand, either from the admin UI trigger simulator or through an API call.

Manual workflows start with an editable object schema. By default, the schema is an object with no predefined properties and `additionalProperties: true`, which means the workflow can receive any object payload until you define stricter fields.

Add fields to the input schema when you want validation, form generation, clearer API contracts, and better expression autocomplete. A manual workflow for order lookup, for example, might define:

| Field             | Type      | Required | Description                                                  |
| ----------------- | --------- | -------- | ------------------------------------------------------------ |
| `order_id`        | `string`  | Yes      | Identifier of the order to look up.                          |
| `include_history` | `boolean` | No       | Whether the workflow should include historical order events. |

Expressions can then read those values from `$input`.

```yaml
defs:
  lookup_order:
    kind: task
    action: http_request
    inputs:
      method: GET
      url: "='https://example.com/orders/' & $input.order_id"

flow:
  - do: lookup_order
```

### Choosing a Type

Choose the type based on who or what starts the workflow:

* Use **conversational** when the trigger is a channel event or incoming chat message.
* Use **scheduled** when the trigger is time-based and should run without an external caller.
* Use **manual** when another system, admin user, or API client decides when to run the workflow and what payload to pass.


---

# 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://docs.hexabot.ai/workflow-editor/workflow-types.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.