> For the complete documentation index, see [llms.txt](https://docs.hexabot.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hexabot.ai/workflow-editor/workflow-types/conversational-workflows-chatbot-message-triggers.md).
# Conversational Workflows: Chatbot Message Triggers
Conversational workflows are Hexabot chatbot workflows that run when connected channels receive messages or events. They automate message-based conversations using the inbound message and current conversation context.
Use conversational workflow automation to build:
* Customer support assistants
* Lead-generation chatbots
* Product recommendation conversations
* FAQ and knowledge-base chatbots
* Multi-step data collection
* Human handover workflows
Unlike Manual and Scheduled workflows, Conversational workflows receive input automatically from the channel event and conversation context.
### Create a chatbot conversational workflow
To create one:
1. Open the Workflow Editor.
2. Create a new workflow.
3. Select **Conversational** under **Type**.
4. Enter a descriptive **Name**.
5. Optionally add a **Description**.
6. Click **Submit**.
The workflow type determines its trigger and available input fields.
> A workflow's type cannot be changed after it has been created.
### Connect a chatbot workflow to a messaging channel
A Conversational workflow must be associated with a channel source before it can process incoming chatbot messages.
See [Which channels are supported in Hexabot?](/faq/which-channels-are-supported-in-hexabot.md) to choose a supported channel, or [build your own](/developer-guide/develop-custom-channels.md).
Open the relevant channel source and select the workflow in the **Workflow** field.
When the source receives a new message, Hexabot starts the selected workflow. It provides the message and conversation context as workflow input.
Different sources can use different conversational workflows. For example, assign one chatbot workflow to a website widget and another to a messaging channel.
### Conversational workflow message input
The input schema of a Conversational workflow is defined by Hexabot and cannot be edited.
The schema is displayed as **Read only** in the workflow form because its values are generated automatically from the incoming channel event.
The workflow can receive the following properties:
| Property | Type | Description |
| -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `message_type` | `string` | The type of inbound message associated with the event, such as text, quick reply, postback, or attachment. |
| `payload` | `object` or `string` | Additional payload supplied by the channel event. Its structure may vary depending on the channel and message type. |
| `message` | `object` | The normalized incoming message object received from the channel. |
| `text` | `string` | Text extracted from the incoming message. |
| `mid` | `string` | The unique identifier of the incoming message, when provided by the channel. |
| `thread_id` | `string` | The identifier of the conversation thread associated with the event. |
The exact values available in `message` and `payload` depend on the connected channel and the type of event received.
### Process incoming chatbot messages
For text-oriented workflows, use the `text` property as the primary message content.
Use `message_type` when the workflow needs different behavior depending on how the user interacted with the channel. For example, the workflow can handle a text message differently from a button postback or file attachment.
The `message` property provides the complete normalized message when additional metadata is required.
The `payload` property can contain channel-specific information, such as the value associated with a quick reply or postback.
### Maintain chatbot conversation context
Every Conversational workflow execution is associated with a conversation thread.
The `thread_id` identifies that thread and allows Hexabot to maintain context across multiple user messages. Messaging actions can use the current execution context to reply through the same channel and conversation.
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`.
### YAML workflow example
```yaml
defs:
reply:
kind: task
action: send_text_message
inputs:
text: "='You said: ' & $input.text"
flow:
- do: reply
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.hexabot.ai/workflow-editor/workflow-types/conversational-workflows-chatbot-message-triggers.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.