> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send message/receive message tasks

> Send message task and Receive message task nodes are used to handle the interaction between a running process and external systems. This is done using Kafka send actions or start integration workflow actions.

Send message and receive message tasks are how a process talks to external systems over Kafka: the send message task publishes a request to a topic, and the receive message task waits for the reply. They typically work as a pair around an integration or plugin call.

## Send message task

This node is used to configure messages that should be sent to external systems.

![Send Message Task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/send-task_node.svg#center)

### Configuring a send message task

Node configuration is done by accessing the **Node Config** tab. You have the following configuration options for a send message task:

#### General Config

Inside the **General Config** tab, you have the following properties:

* **Node Name**: The name of the node
* [**Stage**](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/task-management/using-stages.md): Assign a stage to the node

To configure a send message task, you first need to add a new node and then configure an **action** (**Kafka Send Action** or **Start Integration Workflow** type):

1. Open **Process Designer** (The process designer is a component of FlowX.AI Designer that allows users to create and design business processes using process definitions.) and start configuring a process.
2. Add a **send message task** node.
3. Select the **send message task** node and open the **Node Configuration**.
4. Add an **action** (Actions in the FlowX.AI platform are used to define the activity that a node has to handle. They can have various types and are used to specify the communication details for plugins or integrations.), the type of the action set to **Kafka Send Action** or **Start Integration Workflow**.
5. A few action parameters will need to be filled in depending on the selected action type.

![Actions tab of a send message task showing a Kafka Send Action with Trigger, Execution, Parameters, and Advanced configuration sections](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kafka_send_action.png)

Multiple options are available for this type of action and can be configured via the FlowX.AI Designer. To configure and [add an action to a node](https://docs.flowx.ai/6.x/docs/flowx-designer/managing-a-project-flow/adding-an-action-to-a-node.md), use the **Actions** tab at the node level, which has the following configuration sections:

* [Action Edit](#action-edit)
* [Trigger](#trigger)
* [Execution](#execution)
* Navigation
* [Parameters](#parameters)
* [Advanced configuration](#advanced-configuration)

#### Action Edit

* **Name**: The name of the action
* **Action Type**: The type of the action, should be set to **Kafka Send Action** for actions used to send messages to external systems, or **Start Integration Workflow** to trigger [**workflows**](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md#workflows)

> [!NOTE]
>
> Additional fields like **Order** and **Timer Expression** may also be available in certain configurations to control action execution order and timing.

#### Trigger

* **Manual**: When enabled, the action must be triggered manually by the user. When off (automatic), the action triggers automatically when the process flow reaches this step
* **Repeatable**: When enabled, the action can be triggered multiple times

#### Execution

* **Optional**: When enabled, the action is optional and the process can continue without it being executed. When off (mandatory), the action must be completed before advancing to the next node
* **Autorun Children**: When enabled, child actions (defined as mandatory and automatic) run immediately after the parent action completes

#### Parameters

Parameters define the message details for the Kafka send action:

* **Topics**: The Kafka topic name where the message should be sent
* **Message**: The message payload to send (can include process variables using `${variableName}` syntax)

> [!NOTE]
>
> Parameters can be added either using the **Custom** option (where you configure everything on the spot) or by using **From Integration** to import parameters already defined in an integration.
>
> For more information, see the [Integrations Management documentation](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md).

#### Advanced configuration

* **Show Headers**: When enabled, allows you to configure custom headers for the Kafka message (for example, `processInstanceId`)

![Kafka Send Action with a topic and JSON message, and Show Headers turned on with a pre-filled processInstanceId header](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/kafka-send-action-show-headers.png)

For more information about Kafka, check the following sections:

> [card] [Intro to Kafka](https://docs.flowx.ai/6.x/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts.md)

> [card] [Kafka documentation](https://kafka.apache.org/documentation/)

### Example of a send message task usage

Send a message to a CRM integration to request a search in the local database:

#### Action Edit

* **Name** - pick a name that makes it easy to figure out what this action does, for example, `sendRequestToSearchClient`
* **Action Type** - Kafka Send Action

#### Trigger

* **Manual** - off (automatic trigger)
* **Repeatable** - off (it only needs to run once)

#### Execution

* **Optional** - off (mandatory - the action must be completed before advancing to the next node)
* **Autorun Children** - enabled (if there are child actions, they run automatically)

#### Parameters

* **Topics** - `ai.flowx.in.crm.search.v1` - the Kafka topic on which the CRM listens for requests
* **Message**:

```json theme={"dark"}
// Example of a message payload
{ "clientType": "${application.client.clientType}", "personalNumber": "${personalNumber.client.personalNumber}" }
```

#### Advanced configuration

* **Show Headers**: When enabled, allows you to configure custom headers for the Kafka message (for example, `processInstanceId`, correlation IDs, or other metadata)

## Receive Message Task

This type of node is used when we need to wait for a reply from an external system.

![Receive Message Task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/receive-task%20_node.svg#center)

The reply from the external system will be saved in the process instance values, on a specified key.

For example, let's think about a CRM microservice that waits to receive requests to look for a user in a database. It will send back the response when a topic is configured to listen for the response.

![Receive message task Node Config with Integration Output, Source set to Custom Topic, showing the Topic Name and Key Name fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/receive_kafka_custom.png)

### Configuring a Receive Message Task

Node configuration happens in the **Integration Output** section of the **Node Config** tab.

### Integration Output

The reply arrives on a **data stream**. Click **Add Stream** to add one, then pick its **Source**:

* **Custom Topic**: Type the **Topic Name** the engine listens on and the **Key Name** where the payload lands in the process data.
* **Workflow**: Pick the integration workflow in the **Select workflow** dropdown. With the **Legacy Mapping** toggle **OFF** (the default - see [Legacy mapping vs data mappers](#legacy-mapping-vs-data-mappers)), the **Output Mapping** list shows the workflow's End nodes - configure an output mapping for each one that tells the engine which process attribute receives the workflow's result:

  1. Open the End node's mapping (the wrench icon next to it).
  2. Map the process attribute to the workflow output using `${...}` interpolation syntax.
  3. Click **Test** to preview the mapped result, then **Confirm** to store the mapping.
  4. Save the node - the mapping is persisted only when the node itself is saved.

> [!WARNING]
>
> **Test only previews - Confirm stores.** Closing the mapping modal without clicking **Confirm**, or skipping the node save, leaves the node with no mapping, and every reply then fails at runtime with `workflow output cannot be appended to the process instance due to missing mapping in the data stream`. A failed reply is not retried, so the instance stays blocked on the node - fix the mapping and test with a new process instance. See the [error glossary](https://docs.flowx.ai/6.x/docs/resources/error-glossary.md#workflow-output-cannot-be-appended-to-the-process-instance-due-to-missing-mapping-in-the-data-stream).
>
> The **Update** button next to **Clear** and **Test** (**Select from data model** in newer versions) only adds process attributes to the mapping list. It doesn't store the mapping.

> [!TIP]
>
> To see the full send, workflow, receive round trip built end to end, follow the [Call an external API from a process](https://docs.flowx.ai/6.x/cookbooks/call-external-api.md) cookbook.

#### Legacy mapping vs data mappers

A **Workflow** data stream works in one of two modes, switched per stream with the **Legacy Mapping** toggle:

* **Data mappers** (toggle **OFF**, the default): configure a per-End-node output mapping as described above. The mapping modal is populated from the workflow's declared output parameters, and a broken mapping fails loudly at runtime with the errors listed in the [error glossary](https://docs.flowx.ai/6.x/docs/resources/error-glossary.md#integration-workflow-output). See [Data mappers](https://docs.flowx.ai/6.x/docs/building-blocks/process/data-mappers.md) for the general mapping mechanism.
* **Legacy mapping** (toggle **ON**): type a single **Key Name** instead of configuring a mapping. The entire workflow output payload is stored under that key in the process data, exactly as the End node returns it. If the End node returns `{"value": 1322}` and the key is `result`, downstream nodes read `result.value`. Nothing validates the key against the workflow - it is simply where the payload lands, so a downstream node reading a different key finds no data and no error points at the mismatch.

Both modes work at runtime - they are alternatives, not a migration requirement. Legacy mapping is what older configurations and training material use. Data mappers pair with a declared workflow data model, which is what provides the visual mapping and the runtime output contract.

The same choice exists on the send side: the **Start Integration Workflow** action either uses data mapping driven by the workflow's declared input parameters, or a hand-typed JSON body whose keys must match what the workflow's Start node expects.

> [!NOTE]
>
> A Receive Message Task has no timeout of its own: the token waits on the node indefinitely until the message arrives. To bound the wait, attach an interrupting [timer boundary event](https://docs.flowx.ai/6.x/docs/building-blocks/node/timer-events/timer-boundary-event.md) to the node and route the timeout path from there.


## Related topics

- [Process nodes (BPMN)](https://docs.flowx.ai/6.x/docs/building-blocks/node/node.md)
- [Adding a new node](https://docs.flowx.ai/6.x/docs/flowx-designer/managing-a-project-flow/adding-a-new-node.md)
- [Adding an action to a node](https://docs.flowx.ai/6.x/docs/flowx-designer/managing-a-project-flow/adding-an-action-to-a-node.md)
- [Passing data between nodes](https://docs.flowx.ai/6.x/docs/building-blocks/process/passing-data-between-nodes.md)
- [Error glossary](https://docs.flowx.ai/6.x/docs/resources/error-glossary.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.