saokim-chat-debounce

n8n community node for in-process trailing-edge chat message debounce.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.2
Author: Sao Kim

Available Nodes

Documentation generating…

Sao Kim Chat Debounce icon
Sao Kim Chat Debounce
Debounce and merge bursty chat messages by key.

Documentation

n8n-nodes-saokim-chat-debounce

Sao Kim Chat Debounce is an n8n community node that merges bursty chat messages
into one trailing-edge output.

Typical flow:

Webhook / Facebook / Zalo / WhatsApp
  -> Normalize Message
  -> Sao Kim Chat Debounce
  -> AI Agent
  -> Business Logic
  -> Send Response

What It Does

Chat platforms often send every short customer sentence as a separate webhook.
This node buffers messages by Debounce Key, resets a silence timer whenever a
new message arrives, then emits one merged message after the customer stops.

Older executions emit zero items. The latest execution wins and continues
downstream with the newest metadata.

Installation

Install in your self-hosted n8n community nodes directory:

npm install n8n-nodes-saokim-chat-debounce

Restart n8n after installation if your deployment does not auto-load community
packages.

Configuration

Field Purpose
Debounce Key Customer/session key. Example: ={{ 'zalo:' + $json.user_id }}
Message Text to merge. Example: ={{ $json.message }}
Wait Amount Silence window amount.
Wait Unit Milliseconds or Seconds.
Join Separator Separator for merged messages. Supports \n, \n\n, \r, \t, and \\.
Output Field Name Field that receives merged text. Default: debouncedMessage.
Output Mode Enrich latest item or output debounced data only.
Maximum Messages Safety flush when the buffer reaches this count. Default: 100.
Maximum Wait Optional max seconds from the first message. 0 disables it.

Examples

Facebook:

Debounce Key: ={{ 'facebook:' + $json.sender.id }}
Message: ={{ $json.message.text }}
Wait Amount: 5
Wait Unit: Seconds
Join Separator: \n
Output Field Name: debouncedMessage

Zalo:

Debounce Key: ={{ 'zalo:' + $json.user_id }}
Message: ={{ $json.message }}
Wait Amount: 5
Wait Unit: Seconds
Join Separator: \n

Example output:

{
  "platform": "zalo",
  "userId": "U123",
  "debouncedMessage": "Xin chao\nToi muon hoi dich vu\nben minh nhe",
  "debounce": {
    "key": "zalo:U123",
    "messageCount": 3,
    "firstReceivedAt": "2026-09-24T06:00:00.000Z",
    "lastReceivedAt": "2026-09-24T06:00:03.000Z",
    "waitMs": 5000,
    "flushReason": "silence"
  }
}

Architecture

This node stores active debounce state in the memory of the current n8n
execution process. It is designed for short debounce windows on single-process
deployments.

Isolation scope is:

workflow + node + debounce key

The scope key is built with JSON.stringify([workflowId, nodeId, debounceKey])
to avoid delimiter collisions.

Multiple workflows can use this node on the same n8n installation. Multiple
Message Debounce nodes can also be used in the same workflow. Each node gets an
independent bucket.

Limitations

This node does not coordinate state across multiple workers, processes, or
replicas. In n8n queue mode or horizontally scaled deployments, messages for the
same customer can land in different processes and will not share a buffer.

Active debounce buffers are lost if the n8n process restarts before the debounce
window completes.

The node does not use Redis, a database, filesystem persistence, credentials,
external APIs, telemetry, or environment variables at runtime.

Webhook providers often expect fast acknowledgement. Do not make the external
platform wait for the full debounce period if the provider requires immediate
webhook acknowledgement.

Development

npm install
npm run lint
npm test
npm run build
npm run validate:harness

The local harness lives in docs/. Start with:

  • docs/HARNESS.md
  • docs/ARCHITECTURE.md
  • docs/FEATURE_INTAKE.md
  • docs/TEST_MATRIX.md
  • docs/product/message-debounce.md

Compatibility Notes

The package is structured as a standard n8n community node and uses basic
programmatic node APIs: getInputData(), getNodeParameter(), getNode(),
getWorkflow(), and NodeOperationError.

Target test baseline: n8n-workflow@2.8.3. Do not claim broader n8n runtime
compatibility until tested in an actual n8n instance.

License

MIT.

Discussion