LurkAPI

What is this?

LurkAPI lets your Twitch chat track who is lurking using Nightbot custom commands. When a viewer runs !lurk, the bot records the time. When they run !unlurk, the bot reports how long they were away. No setup is needed beyond adding the commands — Nightbot automatically passes the viewer’s identity in its request headers.

Data is stored per-channel. Lurkers who have been gone for more than 24 hours are automatically pruned.

API Endpoints

All endpoints are GET requests under /api/. They require the standard Nightbot request headers (Nightbot-User and Nightbot-Channel), which Nightbot sends automatically.

Method	Path	Description	Response example
GET	/api/lurk	Start lurking (visible confirmation)	`StreamerName started lurking`
GET	/api/lurksilent	Start lurking (no chat message)	silent — returns a single space
GET	/api/unlurk	Stop lurking with full message	`StreamerName stopped lurking after 1:23:45`
GET	/api/unlurktime	Stop lurking, return duration only	`1:23:45`
GET	/api/lurkers	List all current lurkers in the channel	`Current Lurkers: Alice, Bob, Charlie`

Nightbot Setup

Add these as custom commands in your Nightbot dashboard. Replace lurk.helpful.stream with staging.lurk.helpful.stream to test on staging first.

!lurk — start lurking (shows a message)

$(urlfetch https://lurk.helpful.stream/api/lurk)

!lurk — start lurking (silent, no chat response)

$(urlfetch https://lurk.helpful.stream/api/lurksilent)

!unlurk — stop lurking (full message)

$(urlfetch https://lurk.helpful.stream/api/unlurk)

!unlurk — stop lurking (time only, use in a custom message)

$(user) was lurking for $(urlfetch https://lurk.helpful.stream/api/unlurktime)

!lurkers — list everyone currently lurking

$(urlfetch https://lurk.helpful.stream/api/lurkers)

Nightbot automatically includes the viewer’s identity in its request headers. No API keys, tokens, or extra configuration are required.

How it works

When Nightbot calls a $(urlfetch ...) URL, it attaches Nightbot-User and Nightbot-Channel headers containing the viewer’s Twitch ID, display name, and the channel they’re in. LurkAPI reads these headers, looks up or updates the viewer’s lurk record in a Cloudflare D1 database, and returns a plain-text response that Nightbot posts to chat.

Lurk times are stored as Unix timestamps. The duration is calculated at unlurk time. Entries older than 24 hours are automatically removed when the /api/lurkers endpoint is called.