> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/flows/message-object.md).

# Message Object

#### What is the Message Object?

In a Contextual Flow, the Message Object is a versatile container that holds all data and properties being processed, as they traverse through a flow.

* **Read**: Nodes can access the current properties of the message object, such as `msg.payload`.
* **Modify**: Nodes can change the contents of the message object.
* **Extend**: Nodes can add new properties to the message object, enriching the data structure.

Typically starting with an `msg.payload` property, which contains the primary data from an input node, the message object can be enriched with additional properties such as `msg.topic`, `msg.myCustomProperty`, or any other custom attributes as needed. This flexibility allows for the creation of dynamic and responsive flows, where the message object evolves in real-time, carrying with it all the necessary information required by subsequent nodes. The comprehensive structure of the message object is key to the powerful and modular nature of software built using Contextual.

#### Where does the content of the Message Object come from?

The content of the message object is determined by the source of the data being sent to the flow, so varies widely. In Contextual, it is common for the message object to contain...

* JSON with all details from a create, update, delete, or other action for a [Record](/documentation-and-resources/components-and-data/object-types/object-type-details/records.md) of an [Object Type](/documentation-and-resources/components-and-data/object-types.md)
* JSON with the formatted output of a...

#### HTTP request messages

Messages from an HTTP In node also carry `msg.req` (the incoming request) and `msg.res` (the response handle). Preserve these fields when modifying the message so downstream nodes can inspect the request and send its response.

For JSON `POST` requests handled by a deployed HTTP to Flow agent, `msg.payload` and `msg.req.body` contain parsed JSON at the input node's output, while `msg.req.rawBody` is a `Buffer` captured before JSON parsing. The raw-body property is runtime- and content-type-dependent; it is not present on every message or guaranteed to behave identically across the Flow Editor and a deployed HTTP to Flow agent.

See [HTTP In: request bodies and webhook signatures](/documentation-and-resources/components-and-data/flows/node-reference/network/http-in.md#request-bodies-and-webhook-signatures) for an availability check and limitations. Do not reconstruct a signature input from the parsed payload.

#### Movement of the Message Object in a Flow

1. **Starts at an Input Node**: The journey of the message object begins at an input node, such as an Event Start, HTTP In node, or any other input source. This node receives data and creates a message object, typically containing a `payload` property (`msg.payload`) with the initial data.
2. **Travels Through Processing Nodes**: The message object moves along the wires in the flow to various processing nodes. Each node can read, modify, or extend the properties of the message object.
   * **Example**: A function node can add a timestamp to the message object by including a line like `msg.timestamp = Date.now();`.
3. **Conditional Routing and Transformation**: Nodes like switch nodes or change nodes can conditionally route or transform the message object.
   * **Example**: A switch node might route messages to different outputs based on the value of `msg.payload.severity`.
4. **Extending the Message Object**: Nodes can add new properties to the message object beyond `msg.payload`. This allows for a richer and more complex data structure to be built as the message progresses through the flow.
   * **Example**: An HTTP Post node might interact with an external system using an API call, and add the resulting response to a new `msg.apiResponse` property.
5. **End at an Output Node**: Finally, the message object reaches an output node, such as an HTTP Response node, MQTT Out node, or a database node. This node sends the modified message object to an external system.

```mermaid
graph TD
    A[Input Node]

    subgraph MessageObject1 [Message Object]
        MsgPayload["msg.payload: { data }"]
        MsgTopic["msg.topic: { topic }"]
    end

    subgraph ProcessedMessageObject1 [Processed Message Object]
        MsgPayloadProcessed1["msg.payload: { processed data }"]
        MsgTopicProcessed1["msg.topic: { new topic }"]
    end

    subgraph ModifiedMessageObject [Modified Message Object]
        MsgPayloadProcessed2["msg.payload: { modified data }"]
        MsgTopicProcessed2["msg.topic: { modified topic }"]
        MsgCustomProperty["msg.myCustomProperty: { new data }"]
    end

    A --> MessageObject1
    MessageObject1 --> B[Process Node]
    B --> ProcessedMessageObject1
    ProcessedMessageObject1 --> C[Modify Node]
    C --> ModifiedMessageObject
    ModifiedMessageObject --> D[Output Node]

    style A fill:#4660C9,stroke:#242424,stroke-width:2px,color:#fff
    style B fill:#74ABFF,stroke:#242424,stroke-width:2px,color:#242424
    style C fill:#FFC700,stroke:#242424,stroke-width:2px,color:#242424
    style D fill:#5EDEC7,stroke:#242424,stroke-width:2px,color:#242424
    style MessageObject1 fill:#461E52,stroke:#242424,stroke-width:1px,color:#fff
    style ProcessedMessageObject1 fill:#461E52,stroke:#242424,stroke-width:1px,color:#fff
    style ModifiedMessageObject fill:#461E52,stroke:#242424,stroke-width:1px,color:#fff

```


---

# 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.contextual.io/documentation-and-resources/components-and-data/flows/message-object.md?ask=<question>&goal=<endgoal>
```

`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.