Gravity Update

Send updates for an existing message in Gravity
Join our community

Overview

The Gravity Update node allows users to send various types of updates to an existing message within the Gravity platform. It is designed to facilitate real-time communication and state management in chat or conversational AI workflows by pushing incremental updates such as progress messages, streaming text chunks, structured JSON data, or metadata key-value pairs.

Common scenarios where this node is beneficial include:

  • Sending step-by-step progress updates during a long-running process.
  • Streaming partial text responses as they are generated.
  • Transmitting structured data results for further processing or display.
  • Updating metadata associated with a conversation or message.

For example, in a chatbot workflow, you might use this node to update the user interface with the current status of a task ("Processing your request..."), stream partial answers as they become available, or attach additional structured information like API call results or user preferences.

Properties

Name Meaning
Chat ID Identifier of the chat session to which this update belongs.
Conversation ID Identifier of the conversation, typically passed from a previous Gravity Input node.
User ID Identifier of the user involved in this update.
State (Optional) The overall state of the chat message; defaults to "ACTIVE".
Update Type Type of update to send. Options:
- Progress Update
- Message Chunk
- JSON Data
- Metadata
Enable Audio Generation Whether to generate voice audio for this message (boolean).
Advanced Options Whether to show advanced configuration options (boolean).
Message State (Advanced option) Detailed state of the chat message. Options: Idle, Active, Complete, Thinking, Responding, Waiting, Error, Cancelled
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 Name of the field to use for the JSON data in the output (default: "calls").
Metadata Key Key name 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 details about the update sent:

  • For Progress Update:

    {
  "state": "<message state>",
  "updateType": "progressUpdate",
  "timestamp": "<ISO timestamp>",
  "message": "<progress message text>"
}

  • For Message Chunk:

    {
  "state": "<message state>",
  "updateType": "messageChunk",
  "timestamp": "<ISO timestamp>",
  "textPreview": "<first 30 characters of the text chunk, truncated with ellipsis if longer>"
}

  • For JSON Data:

    {
  "state": "<message state>",
  "updateType": "jsonData",
  "timestamp": "<ISO timestamp>",
  "dataType": "<field name used for JSON data>",
  "itemCount": <number of items in JSON array or 1 if single object>
}

  • For Metadata:

    {
  "state": "<message state>",
  "updateType": "metadata",
  "timestamp": "<ISO timestamp>",
  "key": "<metadata key>",
  "value": "<metadata value>"
}

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 the Gravity SDK's publisher client to send events to the Gravity platform.
  • Requires proper configuration of the Gravity API credentials in n8n.

Troubleshooting

  • Invalid JSON data error: When sending JSON Data updates, the input must be valid JSON. If parsing fails, the node throws an error indicating invalid JSON data. To fix, ensure the JSON string is correctly formatted.
  • Unsupported update type error: If an unknown update type is selected or passed, the node will throw an error. Verify that the update type property is set to one of the supported options.
  • Credential errors: If the Gravity API credentials are missing or incorrect, the node will fail to authenticate. Ensure the API key and server URL are correctly configured.
  • Continue on Fail behavior: If enabled, the node will continue processing subsequent items even if one item fails, returning error details in the output JSON.

Links and References

Discussion