Introduction

Pingui Alert is a lightweight notification service that allows you to send alerts to your Telegram account directly from your code. It's designed to be dead simple to use, with zero configuration required on your server.

Setup & Authentication

To start sending alerts, you need to obtain an API Key from our Telegram bot.

1. Open Telegram and search for @PinguiAlertBot (or your hosted bot instance).
2. Start a chat and send the command /start to register.
3. Send the command /temporal_token to get a temporary access token. (Once you create your first integration, you will get a new permanent token)
4. Use the API to create your first integration and start sending alerts.

The Commandments

To keep Pingui Alert useful and stable for everyone, we adhere to a strict set of rules. Follow these commandments to ensure the best experience.

1. I. Critical Use Only
   You shall use it only for critical alerts that must be corrected immediately. Design your system to trigger these alerts sparingly—only once per incident type (avoid alert storms).
2. II. Production Standards
   If you send errors from your API using our bot, you must follow production best practices. Ensure your error handling is robust before piping it to an alert.
3. III. Self-Host for Customization
   If you require any customization (no matter how simple), you shall use the self-hosted option. You can host Pingui Alert anywhere; we suggest a VPS or a local server due to its minimal resource footprint, but cloud options are also valid.
4. IV. Actionable Alerts
   You shall ensure every alert is actionable. Every alert should prompt a specific, immediate response.
5. V. No Data Leakage
   You shall not send sensitive user data (PII), identifiers, or secrets in your alerts. Keep messages safe and compliant.
6. VI. Fail Safely
   You shall implement error handling so that a failed alert notification never crashes your main application. The alert service failure should be silent to your end users.

Production Usage

When using Pingui Alert in production environments, follow these best practices to ensure optimal service quality for everyone.

Recommended Production Setup

For production workloads with frequent notifications, we recommend one of these approaches:

• Self-Host Your Instance: Deploy your own Pingui Alert server and bot. This gives you full control over rate limits and ensures dedicated resources.
• Use for Critical Alerts Only: If using @PinguiAlertBot, implement filtering logic to send only high-priority notifications (failures, errors, security events).
• Implement Batching: Group multiple non-critical alerts into periodic summary messages instead of sending individual notifications.

Self-Hosting

To self-host Pingui Alert:

git clone https://github.com/juanvidev1/pingui-alert
cd pingui-alert

# Set your environment variables
export BOT_TOKEN="your_telegram_bot_token"
export JWT_SECRET="your_secret_key"
export MAX_ALERTS=100  # Customize your daily limit

# Install dependencies
pnpm install

# Run the server
pnpm run dev

NPM Package

If you are using Node.js or TypeScript, we recommend using our official package in case you just want to send alerts using Pingui Alert server. Rate limit and quota are handled by the server and you need to still use the endpoint createIntegration to get your permanent API KEY.

Installation

npm install pingui-alert

Usage

1. Follow the steps in the Create Integration section to get your permanent API KEY.
2. On the public bot use the command /get_me to get your chatId.
3. Use the API KEY and chatId in the code below:

import { Pingui } from 'pingui-alert';

const client = new Pingui('YOUR_API_KEY');

await client.send('Database backup completed successfully! ✅', 'YOUR_CHAT_ID');

Use Cases

Here are some clear examples of how to apply Pingui Alert in real-world scenarios, strictly adhering to the Commandments.

try {
  await processPayment(orderId, amount);
} catch (error) {
  // ❌ BAD: Sending the full error stack or user PII
  // await client.send(`Payment failed for user ${user.email}: ${error.stack}`);

  // ✅ GOOD: Actionable, specific, safe
  logger.error(error); // Log details locally
  await client.send(
    `🚨 Critical: Payment Gateway Failure\n` +
    `Gateway: Stripe\n` +
    `OrderId: ${orderId}\n` +
    `Action: Check Stripe Status & Logs immediately.`
  );
}

#!/bin/bash
USAGE=$(df / | grep / | awk '{ print $5 }' | sed 's/%//g')

# Only alert if usage is > 90% (Critical)
if [ "$USAGE" -gt 90 ]; then
  curl -X POST https://api.pingui-alert.dev/alert \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "alert": "💾 Server Disk Critical\nUsage is at '"$USAGE"'%.\nClean up logs or expand volume NOW."
    }'
fi

if (failedAttempts > 10) {
  // Block IP logic...

  // Alert Security Team
  await client.send(
    `🛡️ Security Alert: Brute Force Detected\n` +
    `IP: ${req.ip}\n` +
    `Attempts: ${failedAttempts}\n` +
    `Action: IP has been temporarily banned. Verify traffic source.`
  );
}

job.on('failed', async (err) => {
  try {
    await client.send(
      `💥 Backup Job Failed\n` +
      `Job: nightly_db_backup\n` +
      `Error: Connection timeout\n` +
      `Action: Manually retry backup via admin panel.`
    );
  } catch (alertError) {
    // Fail safely - do not crash the worker if alert fails
    console.error('Failed to send alert:', alertError);
  }
});