Gravity Output

Send various message types to clients
Join our community

Overview

The Gravity Output node sends various types of messages to clients connected via the Gravity platform. It supports multiple message formats such as plain text, JSON data, MDX components, images, tool outputs, and action suggestions. This node is useful in scenarios where you want to programmatically push rich content or structured data into a chat or conversation interface managed by Gravity.

Practical examples include:

  • Sending a simple text response to a chat.
  • Delivering structured JSON data for client-side processing.
  • Displaying interactive MDX components within a conversation.
  • Showing images with optional alt text.
  • Reporting results from external tools.
  • Suggesting user actions based on AI or workflow logic.

Properties

Name Meaning
Chat ID Identifier of the chat session to which the message will be sent.
Conversation ID Identifier of the conversation (should match the one from the Gravity Input node).
User ID Identifier of the user involved in the conversation.
Advanced Options Toggle to show advanced configuration options like message state and error handling behavior.
Message State State of the chat message; options: Idle, Active, Complete, Thinking, Responding, Waiting, Error, Cancelled. (Shown only if Advanced Options enabled)
Output Type Type of output message to send; options: Text, JSON Data, MDX Component, Image Response, Tool Output, Action Suggestion.
Text Content Text string content to send (required if Output Type is Text).
JSON Data JSON string representing data payload (required if Output Type is JSON Data, Tool Output, or Action Suggestion).
JSON Data Field Name Field name under which JSON data will be wrapped (only for JSON Data output type).
MDX Code MDX code string to send (required if Output Type is MDX Component).
Image URL URL of the image to display (required if Output Type is Image Response).
Image Alt Text Alternative text description for the image (optional, shown if Output Type is Image Response).
Tool Name Name of the tool that generated the output (required if Output Type is Tool Output).
Action Type Type of action suggested to the user (required if Output Type is Action Suggestion).
Error Handling How to handle errors during execution; options: Throw Error (stop execution), Continue (log error and proceed). (Shown only if Advanced Options enabled)

Output

The node outputs an array of items, each containing a json object with the following fields:

  • success: Boolean indicating whether the message was sent successfully.
  • outputType: The type of output message sent (e.g., text, json_data).
  • state: The message state used when sending.
  • timestamp: ISO 8601 timestamp of when the message was sent.
  • conversationId: The conversation identifier used.
  • chatId: The chat identifier used.
  • userId: The user identifier used.
  • If an error occurs and error handling is set to continue, an error field with the error message is included instead of success.

No binary data output is produced by this node.

Dependencies

  • Requires an API key credential for authenticating with the Gravity server.
  • Needs the Gravity server URL and API key configured in the credentials.
  • Uses the Gravity SDK (@gravityai-dev/gravity-server) to create and publish events.
  • Requires matching conversation IDs from the Gravity Input node to correlate messages properly.

Troubleshooting

  • Missing Required IDs: If Chat ID, Conversation ID, or User ID are empty, the node throws an error. Ensure these are correctly provided and match the input source.
  • Invalid JSON Data: When sending JSON Data, Tool Output, or Action Suggestion, the JSON string must be valid. Invalid JSON will cause an error.
  • Unsupported Output Type: If an unsupported output type is selected, the node throws an error.
  • Error Handling Behavior: By default, errors stop execution. Enabling "Continue" in error handling allows the workflow to proceed while logging errors.
  • Credential Issues: Failure to authenticate with the Gravity server due to missing or invalid API keys will cause errors.
  • Message State Misconfiguration: Using message states without enabling advanced options may lead to unexpected defaults.

Links and References

Discussion