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

LibertyTools / Docs

Use Poll with LibertyJS

Poll is for a bot or app you run yourself. It asks LibertyTools for new ER:LC events using a private token, so you do not need to expose your bot to incoming internet traffic.

1. Set up a Poll client

  1. Create a dashboard connection and paste its ER:LC webhook URL into the server's Event Webhook setting.
  2. Open Outputs → Poll clients and create a client for your bot.
  3. Copy the subscription ID and Poll token immediately. The token is shown once.

The subscription ID chooses which backlog to read. The token proves your bot may read it. The public webhook URL is only for receiving events from ER:LC.

2. Run a LibertyJS bot

This walkthrough uses Node.js 22 or newer so Node can load a .env file directly. Install Node.js from the official download page if needed, then reopen your terminal. Check with node --version. Open a terminal or PowerShell window and create a folder for your bot:

mkdir liberty-bot
cd liberty-bot
npm init -y
npm install @libertytools/libertyjs

In that folder, create a plain text file named exactly .env (not .env.txt). Replace each placeholder below with your own value. Do not paste these lines directly into PowerShell:

ERLC_SERVER_KEY=your-own-server-key
POLL_SUBSCRIPTION_ID=the-id-from-Outputs
POLL_TOKEN=the-private-token-from-Outputs

Create another file named .gitignore containing .env so Git does not upload your credentials. Keep both files in the bot folder.

Save the following as bot.mjs in the same folder, or download bot.mjs. The .mjs extension makes it an ES module without changing package settings.

import LibertyJS from '@libertytools/libertyjs';

for (const name of ['ERLC_SERVER_KEY', 'POLL_SUBSCRIPTION_ID', 'POLL_TOKEN']) {
  if (!process.env[name]?.trim()) throw new Error(`Missing ${name}. Start with node --env-file=.env bot.mjs`);
}
const erlc = new LibertyJS({
  SERVER_KEY: process.env.ERLC_SERVER_KEY,
  POLL_SUBSCRIPTION_ID: process.env.POLL_SUBSCRIPTION_ID,
  POLL_TOKEN: process.env.POLL_TOKEN
});

erlc.commands.command('help', async context => {
  const result = await context.reply('How can we help?');
  if ('error' in result || result.failures > 0) {
    console.error('Reply was not confirmed. Check ER:LC permissions and your server key.');
  }
});
erlc.commands.on('pollError', () => console.error('Poll request failed. Check your connection, subscription ID, and token.'));
console.log('Listening for ;help. Keep this terminal open; press Ctrl+C to stop.');
await erlc.commands.start();

Run this from the bot folder. The --env-file option loads your values; node bot.mjs alone does not read .env:

node --env-file=.env bot.mjs

You should see Listening for ;help. Join your ER:LC server and run ;help, then check for a private reply. Keep the terminal open; press Ctrl+C to stop the bot. If there is no reply, check Events in the dashboard first, then the bot's terminal and ER:LC command permissions.

Your bot must keep running. If you want the command to work while your bot is off, use a hosted command instead.

How delivery works

Each Poll client has its own pending events. LibertyJS follows every Poll page and acknowledges a v2 event after its command handler completes. If a handler throws, that event stays pending for a later retry. If a reply or announcement returns an error, decide whether to throw so it can be retried. A separate Poll client has its own backlog. Make external actions safe to repeat because acknowledgement can fail after an action succeeds.

Pending Poll events expire after 14 days. Each subscription holds at most 5,000 pending events, dropping the oldest when full. The dashboard shows pending and dropped counts. Poll reads are limited to 120 per minute per subscription; respect retry responses instead of repeatedly requesting immediately.

Common problems

  • 401 or 403: check that the subscription ID and token belong together; rotate an exposed or lost token. Check the dashboard for restrictions. A paused or restricted connection can return 404.
  • No events: check the ER:LC webhook URL, then check the dashboard Events tab. If Events has nothing, Poll cannot receive anything.
  • Event appears but no private reply: check the bot process, its pollError logs, the server key, and ER:LC command permissions.
  • Bot restarts: inspect the pending and dropped counts after reconnecting, especially if it was offline for a long time.

See the SDK README and examples for all methods and TypeScript types.