Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to ntfy

Scalekit connector
Open markdown

The ntfy connector lets your AI agent act in each user's ntfy account. Each user connects their own ntfy access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 5 tools.

Tools
5
What they doRead · write · destructive
2 · 2 · 12 read2 write1 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the ntfy connection

    In AgentKit > Connections, create a ntfy connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'ntfy'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize ntfy:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'ntfy_health_get',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their ntfy credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • ntfy_health_getCheck that the ntfy server is up.Read-only

    Get Server Health

    Check that the ntfy server is up. Returns healthy: true when it is. Use this to confirm the server address is right.

    Inputs

    This tool takes no inputs.

  • ntfy_messages_pollRead the messages cached on one or more topics, optionally since a time or message, including scheduled ones, filtered by priority, tags, title or message.Read-only

    Poll Messages

    Read the messages cached on one or more topics, optionally since a time or message, including scheduled ones, filtered by priority, tags, title or message. Returns newline-delimited JSON: one object per event with id, time, event, topic, title, message, priority, tags and attachment fields. Pass since=<last message id> when polling repeatedly to avoid re-reading the whole cache.

    Inputs

    topicsstringrequired
    Topic name, or several separated by commas (up to 150). Example: backups-alerts.
    idstring
    Only the message with this exact ID. Example: pbkiz8SD7ZxG.
    messagestring
    Only messages with exactly this text. Example: Backup finished.
    prioritystring
    Only messages with any of these priorities, comma-separated (1-5 or min, low, default, high, urgent). Example: high,urgent.
    scheduledstring
    1 also returns messages scheduled for later delivery. Example: 1.one of 10
    sincestring
    Return messages since a duration (10m), Unix timestamp, message ID, latest (newest message only) or all (default). Example: 10m.
    tagsstring
    Only messages that have all of these tags, comma-separated. Example: error,backup.
    titlestring
    Only messages with exactly this title. Example: Backup report.
  • ntfy_message_publishSend a push notification to an ntfy topic, with optional title, priority, tags/emojis, click URL, attachment URL, action buttons, Markdown, scheduled delivery, email or phone call.Write

    Publish Message

    Send a push notification to an ntfy topic, with optional title, priority, tags/emojis, click URL, attachment URL, action buttons, Markdown, scheduled delivery, email or phone call. Returns the published message with its id, time, topic and fields. Reuse sequence_id (or a returned id) to replace an earlier notification; use ntfy_notification_clear or ntfy_notification_delete to dismiss it.

    Inputs

    topicstringrequired
    Topic to publish to (letters, digits, - and _, up to 64 characters). Anyone who knows a public topic name can read it, so use hard-to-guess names or reserved topics. Example: backups-alerts.
    actionsarray
    Up to 3 action buttons. Each has action (view, broadcast, http or copy), label, and for view and http a url; http actions can also set method, headers and body. Example: [{"action": "view", "label": "Open dashboard", "url": "https://status.example.com"}]
    attachstring
    URL of a file to attach to the notification. Example: https://example.com/report.pdf.
    callstring
    Also place a voice call reading the message to this verified phone number (or yes). Needs a plan that includes calls. Example: +12223334444.
    clickstring
    URL opened when the notification is tapped. Example: https://status.example.com.
    delaystring
    Schedule delivery: a Unix timestamp, a duration such as 30min, or a time such as 9am or tomorrow 10am (10 seconds to 3 days ahead). Example: 30min.
    emailstring
    Also send the notification to this email address (or yes for your verified address). Rate limited, and may need a paid plan on ntfy.sh. Example: ops@example.com.
    filenamestring
    File name shown for the attachment. Example: report.pdf.
    iconstring
    URL of a JPEG or PNG icon for the notification (Android). Example: https://example.com/icon.png.
    markdownboolean
    Render the message as Markdown (web app and Android). Example: false.
    messagestring
    Notification body. Defaults to triggered when empty. Example: Disk space is low at 5.1 GB.
    priorityinteger
    Priority from 1 (min) to 5 (max); 3 is the default, 4 high, 5 urgent. Example: 4.one of 12345
    sequence_idstring
    Sequence ID that links updates: publishing again with the same ID replaces the earlier notification. Example: my-download-123.
    tagsarray
    Tags; names that match an emoji short code (for example warning, white_check_mark) are shown as emojis. Example: ["warning", "backup"]
    timezonestring
    IANA time zone for natural-language delay values. Example: Europe/Berlin.
    titlestring
    Notification title. Example: Low disk space alert.
  • ntfy_notification_clearMark a delivered notification as read and dismiss it on subscribed clients.Write

    Clear Notification

    Mark a delivered notification as read and dismiss it on subscribed clients. Returns the message_clear event. Use ntfy_notification_delete to remove it from clients entirely.

    • Idempotent

    Inputs

    sequence_idstringrequired
    Sequence ID of the notification: the sequence_id you published with, or the message id returned when it was published. Example: my-download-123.
    topicstringrequired
    Topic name (letters, digits, - and _, up to 64 characters). Example: backups-alerts.
  • ntfy_notification_deleteRemove a notification from subscribed clients, or cancel a scheduled message that has not been delivered yet.Destructive

    Delete Notification

    Remove a notification from subscribed clients, or cancel a scheduled message that has not been delivered yet. Returns the message_delete event. Use ntfy_notification_clear to only mark it as read.

    • Idempotent

    Inputs

    sequence_idstringrequired
    Sequence ID of the notification: the sequence_id you published with, or the message id returned when it was published. Example: my-download-123.
    topicstringrequired
    Topic name (letters, digits, - and _, up to 64 characters). Example: backups-alerts.