Skip to content
WebsiteDocumentationDashboard ↗LibertyJS repo ↗npm package ↗GitHub organization ↗

LibertyTools / Docs

Read Poll events without an SDK

Learn the HTTP read, process, and acknowledge loop using plain Node.js.

← All examples

Download project ZIP

What it does

Read ERLC events with ordinary HTTP, without an SDK or ERLC server key. This Node.js example shows the flow you can port to another language. It logs event types and IDs, then acknowledges them.

What you need

  • Node.js 22 or newer.
  • A LibertyTools connection with its webhook URL configured in ERLC.
  • A separate Poll client under Outputs → Poll clients, with subscription ID and private token. Choose the events you want to consume.

Use a separate client so this reader does not acknowledge another bot's backlog. This reader acknowledges even events it only logs.

Setup

  1. Download and extract the entire project ZIP. Keep poll-client.mjs beside the read-poll folder.
  2. Open a terminal in the extracted read-poll folder.
  3. Copy .env.example to .env. Fill in the subscription ID and token using a text editor. Do not paste secrets into PowerShell, AI chat, or Git. Check the filename is not .env.txt.
  4. Run:
npm start

No package installation is needed. Keep the process running; Ctrl+C stops it.

Test it

Trigger an event in ERLC, such as ;help. Expect Handled CustomCommand (evt_...) in the terminal. The first read reports the cumulative drop count. This reader sends no commands; another handler for ;help can still run.

Change the handler

Replace the logging function in bot.mjs. Return only after your work succeeds. Throw on failure to leave the event pending. Return normally when deliberately ignoring an event to acknowledge it.

Delivery rules

  • Read oldest first and follow pages while hasMore is true. Restart each scan without a cursor so earlier failed events are retried.
  • Acknowledge completed work only. Inspect acknowledged, alreadyAcknowledged, and unknown.
  • The starter waits two seconds between scans, honors retry delays, times out requests, and backs off during outages. Invalid credentials or a paused/restricted connection stop it for investigation.
  • Up to 5,000 completed IDs are remembered in memory. An acknowledgement retry does not rerun a remembered handler. Restarting loses this memory: persist IDs alongside side effects when duplicates matter.
  • Events removed by retention, backlog, or storage limits cannot be recovered. Check dropped counts and the dashboard.

Common problems

  • 401: check the subscription/token pair; rotate exposed or lost tokens.
  • 404: check whether the connection was deleted, paused, or restricted.
  • 429: wait for the retry delay. Do not run extra copies to bypass limits.
  • No events: check Events and the subscription filters.

The reusable HTTP code is in poll-client.mjs, one folder above bot.mjs. See the API reference for response fields and limits.

View bot.mjs
import { pathToFileURL } from 'node:url';
import { createPollClient, required, shutdownSignal } from '../poll-client.mjs';
export async function main(env = process.env) {
  const client = createPollClient({ subscriptionId: required(env, 'POLL_SUBSCRIPTION_ID'), token: required(env, 'POLL_TOKEN') });
  let previousDrops;
  console.log('Reading Poll events. Ctrl+C stops the reader.');
  await client.run(async event => {
    console.log(`Handled ${event.type || 'Unknown'} (${event.id})`);
    // Replace this with your handler. Throw on failure to leave the event pending.
    // Do not print raw payloads or secrets into logs.
  }, { signal: shutdownSignal(), onPage: page => {
    if (page.droppedCount !== previousDrops) {
      console.log(`Subscription drop count: ${Number(page.droppedCount || 0)}. Check the dashboard for retention losses.`);
      previousDrops = page.droppedCount;
    }
  } });
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch(error => {
  console.error(error.message); process.exitCode = 1;
});