Gravity Update

Send updates for an existing message in Gravity
Join our community

Overview

The Gravity Update node allows sending various types of updates to an existing message in the Gravity platform. It is useful for workflows that need to communicate real-time progress, stream text chunks, send structured JSON data, or update metadata related to a chat conversation.

Common scenarios include:

  • Reporting step-by-step progress in a multi-step AI or automation process.
  • Streaming partial text responses as they are generated.
  • Sending complex structured data (e.g., API call results) back into the conversation.
  • Adding or updating key-value metadata associated with a chat.

For example, you might use this node to update a user interface with progress messages during a long-running task, stream AI-generated text as it becomes available, or attach additional JSON-formatted data to a conversation for downstream processing.

Properties

Name Meaning
Chat ID Identifier of the chat to which the update belongs.
Conversation ID Identifier of the conversation, typically passed from a previous Gravity Input node.
User ID Identifier of the user associated with this update.
Update Type Type of update to send. Options: Progress Update, Message Chunk, JSON Data, Metadata.
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 shown if Advanced Options enabled.
Progress Message Text content for a progress update. Required if Update Type is Progress Update.
Text Text chunk content to send. Required if Update Type is Message Chunk.
JSON Data Structured JSON string to send. Required if Update Type is JSON Data.
JSON Data Field Name Field name used to label the JSON data in the output. Defaults to "calls".
Metadata Key Key for the metadata update. Required if Update Type is Metadata.
Metadata Value Value for the metadata update. Required if Update Type is Metadata.

Output

The node outputs an array of items, each containing a json object with the result of the update operation:

  • For Progress Update:

    {
  "success": true,
  "updateType": "progressUpdate",
  "timestamp": "ISO timestamp",
  "message": "Progress update message text"
}

  • For Message Chunk:

    {
  "success": true,
  "updateType": "messageChunk",
  "timestamp": "ISO timestamp",
  "textPreview": "First 30 characters of the text chunk..."
}

  • For JSON Data:

    {
  "success": true,
  "updateType": "jsonData",
  "timestamp": "ISO timestamp",
  "dataType": "Name of the JSON data field",
  "itemCount": Number of items in the JSON array or object
}

  • For Metadata:

    {
  "success": true,
  "updateType": "metadata",
  "timestamp": "ISO timestamp",
  "key": "Metadata key",
  "value": "Metadata value"
}

If an error occurs and the node is configured to continue on failure, the output item will contain:

{
  "success": false,
  "error": "Error message"
}

The node does not output binary data.

Dependencies

  • Requires an external Gravity API service endpoint and an API key credential for authentication.
  • The node uses these credentials to create a publisher client that sends events to the Gravity server.
  • No additional environment variables or n8n configurations are required beyond setting up the API credentials.

Troubleshooting

  • Invalid JSON Data: If the JSON Data property contains invalid JSON, the node throws an error indicating invalid JSON data at the specific item index. Ensure the JSON string is well-formed.
  • Unsupported Update Type: If an unsupported update type is selected, the node throws an error specifying the unsupported type.
  • Credential Issues: Failure to authenticate with the Gravity API due to missing or incorrect API key or server URL will cause errors. Verify credentials are correctly configured.
  • Continue On Fail Behavior: If enabled, the node will output error details per item instead of stopping execution. This helps in batch processing scenarios where some updates may fail but others succeed.

Links and References

Discussion