Gravity Output

Send various message types to clients

Overview

The Gravity Output node is designed to send various types of messages to clients within a chat or conversation context managed by the Gravity platform. It supports multiple output formats such as text, JSON data, images, tool outputs, and action suggestions. This flexibility makes it useful for workflows that need to communicate rich content or structured data back to users or other systems in real-time.

Common scenarios include:

  • Sending chatbot responses with optional voice generation.
  • Delivering structured JSON payloads for downstream processing or UI rendering.
  • Displaying images dynamically based on workflow results.
  • Reporting outputs from external tools integrated into the workflow.
  • Suggesting user actions based on AI or business logic.

For example, a customer support automation could use this node to send text replies, show product images, or suggest next steps to the user.

Properties

Name Meaning
Chat ID Identifier of the chat session where the message will be sent.
Conversation ID Identifier of the conversation, must match the one from the Gravity Input node.
User ID Identifier of the user receiving the message.
Enable Audio Generation Whether to generate a voice version of the message (text-to-speech).
Advanced Options Toggle to show advanced configuration options.
Message State State of the chat message; options: Idle, Active, Complete, Thinking, Responding, Waiting, Error, Cancelled. Only visible if advanced options enabled.
Output Type Type of output to send; options: Text, JSON Data, Image Response, Tool Output, Action Suggestion.
Text Content Text content to send (required if Output Type is Text).
JSON Data JSON string representing data to send (required if Output Type is JSON Data, Tool Output, or Action Suggestion).
JSON Data Field Name Field name under which JSON data will be nested (only for JSON Data output type).
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, only for 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; options: Throw Error (stop execution), Continue (log error and continue). Only visible 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 sent (e.g., text, json_data, image_response).
  • state: The state of the chat message as set in the input.
  • timestamp: ISO string timestamp of when the message was processed.
  • conversationId: The conversation ID used.
  • chatId: The chat ID used.
  • userId: The user ID used.
  • If an error occurs and error handling is set to continue, an error field with the error message is included instead of success.

The node does not output binary data.

Dependencies

  • Requires an API key credential for the Gravity platform to authenticate requests.
  • Uses the Gravity server SDK (@gravityai-dev/gravity-server) to create and publish messages.
  • Needs proper configuration of the Gravity API server URL and API key in the node credentials.
  • The node expects the conversation ID to match one previously established by a Gravity Input node in the workflow.

Troubleshooting

  • Missing Required IDs: If Chat ID, Conversation ID, or User ID are missing, the node throws an error. Ensure these are correctly provided and match existing sessions.
  • 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 will throw an error.
  • Error Handling Behavior: By default, errors stop workflow execution. Enabling advanced options allows choosing to log errors and continue, which can help avoid workflow interruptions.
  • API Credential Issues: Authentication failures due to incorrect or missing API keys will prevent message publishing.
  • Network or Server Errors: Connectivity issues with the Gravity API server may cause failures; verify network access and server status.

Links and References

Discussion