Plugin API

Plugin API

Short reference. Full detail: Authoring, Permissions, Popup spec.

A plugin is a folder with plugin.json and one JavaScript file. The manifest declares providers (conditions and actions) that call global functions in the script.

An action from a package that declares popup can also be chosen as a topic's popup style; it is called exactly like a rule action.

Functions

function myCondition(ctx, params) { return true; }          // condition: true or false
function myAction(ctx, params) { return { popup: {...} }; } // action: undefined or {popup} (needs "ui")
function onPopupAction(ctx, buttonId, state) { return { close: true }; } // optional

Any other return type is an error. A thrown exception is logged and the rest of NtfyBar keeps running.

ctx

Field	Contains
ctx.message	id, time, title, message, priority (1 to 5), tags, click, icon, actions, attachment, contentType, isCatchUp
ctx.topic	{id, label} (NtfyBar's id and your label)

Topic names and server addresses are replaced by [topic] and [server]. params holds the values the user typed in the rule editor.

ntfy methods

A method exists only while its permission is granted. Check before you call.

Method	Permission	Notes
ntfy.history({topicId?, before?, after?, limit?})	history.read	newest first, default 50, max 200; another topic also needs topics.read
ntfy.topics()	topics.read	[{id, label}]
ntfy.publish({topicId, message, title?, priority?, tags?, click?, delay?})	publish	10 per minute per plugin, quiet hours cap priority; delay 10 s – 3 days schedules it (1.1+)
ntfy.copy(text)	clipboard.write	up to 1 MB
ntfy.openURL(url)	openURL	http/https only
ntfy.storage.get/set/remove(key)	storage	1 MB per plugin
return {popup: spec}	ui	see the popup spec

A failed call throws a JavaScript error.

Environment and limits

• Plain JavaScript (JavaScriptCore). No fetch, XMLHttpRequest, require, timers, process or DOM.
• One call may run 1 second. After three timeouts the plugin is disabled until Reload Plugins.
• Call ntfy methods inside functions, not at the top level of the script.
• Files: 2 MB each, 10 MB per package.
• Popup: 20 blocks, 3 buttons, state 64 KB.