nextjs-telegram-notify

📱 nextjs-telegram-notify

A lightweight Next.js package for sending notifications to Telegram. Perfect for contact forms, bug reports, user feedback, and any notification needs.

✨ Features

• 🚀 Simple Integration - Get started in under 5 minutes
• 🔒 Secure - Server-side Telegram API integration
• 📝 TypeScript - Full type safety out of the box
• 🎨 Flexible - Works with any form library or custom UI
• 📎 File Support - Send documents, images, and attachments
• ⚡ Lightweight - Minimal dependencies, < 20KB gzipped
• 🔄 Auto Retry - Built-in retry logic with exponential backoff
• 🎯 Generic - Not limited to forms - works for any notification scenario

📦 Installation

npm install nextjs-telegram-notify

yarn add nextjs-telegram-notify

pnpm add nextjs-telegram-notify

🚀 Quick Start

1. Set up your Telegram Bot

• Create a bot via @BotFather on Telegram
• Get your bot token
• Get your chat ID using @userinfobot or @getidsbot

2. Add Environment Variables

Create a .env.local file in your Next.js project:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

3. Create API Route

Create app/api/telegram-notify/route.ts:

// For default setup - just one line!
export { POST } from 'nextjs-telegram-notify/route';

4. Use in Your Components

'use client';

import { useTelegramNotify } from 'nextjs-telegram-notify';

export default function ContactForm() {
  const { send, loading, error } = useTelegramNotify();

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    await send({
      message: 'New contact form submission!',
      parseMode: 'HTML'
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <button disabled={loading}>
        {loading ? 'Sending...' : 'Submit'}
      </button>
      {error && <p>Error: {error.message}</p>}
    </form>
  );
}

That's it! 🎉

📚 Usage Examples

Contact Form

'use client';

import { useTelegramNotify } from 'nextjs-telegram-notify';
import { useState } from 'react';

export default function ContactForm() {
  const { send, loading, error, success } = useTelegramNotify();
  const [formData, setFormData] = useState({
    name: '',
    email: '',
    message: ''
  });

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    const message = `
📬 <b>New Contact Form Submission</b>

👤 Name: ${formData.name}
📧 Email: ${formData.email}
💬 Message: ${formData.message}

${new Date().toLocaleString()}
    `.trim();

    await send({ message, parseMode: 'HTML' });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={formData.name}
        onChange={(e) => setFormData({ ...formData, name: e.target.value })}
        placeholder="Name"
        required
      />
      <input
        type="email"
        value={formData.email}
        onChange={(e) => setFormData({ ...formData, email: e.target.value })}
        placeholder="Email"
        required
      />
      <textarea
        value={formData.message}
        onChange={(e) => setFormData({ ...formData, message: e.target.value })}
        placeholder="Message"
        required
      />
      <button type="submit" disabled={loading}>
        {loading ? 'Sending...' : 'Send Message'}
      </button>
      {error && <p className="error">{error.message}</p>}
      {success && <p className="success">Message sent successfully!</p>}
    </form>
  );
}

Bug Report Button

'use client';

import { useTelegramNotify } from 'nextjs-telegram-notify';

export default function BugReportButton() {
  const { send, loading } = useTelegramNotify();

  const reportBug = async () => {
    await send({
      message: `
🐛 <b>Bug Report</b>

📄 Page: ${window.location.href}
🖥️ User Agent: ${navigator.userAgent}
⏰ Time: ${new Date().toISOString()}
      `.trim(),
      parseMode: 'HTML'
    });
  };

  return (
    <button onClick={reportBug} disabled={loading}>
      🐛 Report Bug
    </button>
  );
}

File Upload

'use client';

import { useTelegramNotify } from 'nextjs-telegram-notify';

export default function FileUploadForm() {
  const { send, loading } = useTelegramNotify();

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const file = formData.get('file') as File;

    await send({
      message: '📎 New file uploaded',
      files: [file]
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="file" name="file" required />
      <button type="submit" disabled={loading}>Upload</button>
    </form>
  );
}

Server-Side Usage

// app/api/feedback/route.ts
import { sendTelegramNotification } from 'nextjs-telegram-notify/server';

export async function POST(request: Request) {
  const { rating, comment } = await request.json();

  await sendTelegramNotification({
    message: `
⭐ <b>User Feedback</b>

Rating: ${'⭐'.repeat(rating)}
Comment: ${comment}
    `.trim(),
    parseMode: 'HTML'
  });

  return Response.json({ success: true });
}

Security Features

Rate Limiting

Protect your API endpoint from abuse with built-in rate limiting:

import { createTelegramRoute } from 'nextjs-telegram-notify/route';

export const POST = createTelegramRoute({
  rateLimit: {
    maxRequests: 10,       // Max requests per window
    windowMs: 60000,       // Time window in milliseconds (1 minute)
  }
});

Default Limits:

• Per-IP: 20 requests per minute
• Global (Telegram API): 30 requests per second

Rate Limit Headers:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1234567890

Disable Rate Limiting:

export const POST = createTelegramRoute({
  rateLimit: false
});

CORS Configuration

Control which origins can access your API:

export const POST = createTelegramRoute({
  cors: {
    origin: 'https://yourdomain.com',  // Specific origin
    methods: ['POST', 'OPTIONS'],
    allowedHeaders: ['Content-Type'],
    credentials: false,
  }
});

Multiple Origins:

cors: {
  origin: ['https://yourdomain.com', 'https://app.yourdomain.com'],
}

Wildcard (Development Only):

cors: {
  origin: '*',  // Allow all origins - not recommended for production
}

Disable CORS:

export const POST = createTelegramRoute({
  cors: false
});

Security Best Practices

• Always use environment variables for sensitive data
• Enable rate limiting to prevent abuse
• Restrict CORS to your domain only
• Use lifecycle hooks for logging and monitoring
• Validate input on the server side

Complete Security Example:

// app/api/telegram-notify/route.ts
import { createTelegramRoute } from 'nextjs-telegram-notify/route';

export const POST = createTelegramRoute({
  // Rate limiting
  rateLimit: {
    maxRequests: 10,
    windowMs: 60000,
  },
  
  // CORS protection
  cors: {
    origin: process.env.NEXT_PUBLIC_APP_URL!,
    credentials: false,
  },
  
  // Logging
  onBeforeSend: async (request) => {
    console.log('Notification request:', {
      timestamp: new Date().toISOString(),
      messageLength: request.message.length,
    });
  },
  
  // Error tracking
  onError: async (error) => {
    console.error('Notification failed:', error);
    // Report to your error tracking service
  },
});

🔧 API Reference

useTelegramNotify(config?)

Client-side React hook for sending notifications.

Parameters:

• config (optional):
  • endpoint?: string - API endpoint (default: /api/telegram-notify)
  • onSuccess?: () => void - Success callback
  • onError?: (error: Error) => void - Error callback

Returns:

• send: (options: NotifyOptions) => Promise<void> - Send notification function
• loading: boolean - Loading state
• error: Error | null - Error state
• success: boolean - Success state
• reset: () => void - Reset state function

sendTelegramNotification(options)

Server-side function for sending notifications.

Parameters:

• options: NotifyOptions:
  • message: string - Message text (required)
  • parseMode?: 'HTML' | 'Markdown' | 'MarkdownV2' - Message formatting
  • files?: FileAttachment[] - File attachments
  • chatId?: string - Override default chat ID
  • disableNotification?: boolean - Silent notification
  • threadId?: number - Forum topic thread ID

Utility Functions

import {
  formatMessageWithTimestamp,
  escapeHtml,
  escapeMarkdown,
  validateFileSize,
  validateFileType,
  formatFormData,
  createNotification
} from 'nextjs-telegram-notify';

createNotification(options)

Helper for creating structured notification messages:

const message = createNotification({
  title: 'New Order',
  emoji: '🛒',
  fields: {
    'Order ID': '#12345',
    'Customer': 'John Doe',
    'Total': '$99.99'
  },
  includeTimestamp: true
});

🎨 Message Formatting

HTML Format

await send({
  message: `
<b>Bold text</b>
<i>Italic text</i>
<code>Code</code>
<a href="https://example.com">Link</a>
  `.trim(),
  parseMode: 'HTML'
});

Markdown Format

await send({
  message: `
**Bold text**
_Italic text_
\`Code\`
[Link](https://example.com)
  `.trim(),
  parseMode: 'Markdown'
});

🔒 Security Best Practices

• Never expose your bot token - Keep it in server-side environment variables
• Validate user input - Sanitize data before sending to Telegram
• Implement rate limiting - Prevent spam/abuse of your notification endpoint
• Use CAPTCHA - For public-facing forms to prevent bot submissions
• Validate file uploads - Check file types and sizes before sending

🛠️ Advanced Configuration

Custom API Route with Hooks

// app/api/telegram-notify/route.ts
import { createTelegramRoute } from 'nextjs-telegram-notify/route';

export const POST = createTelegramRoute({
  onBeforeSend: async (request) => {
    // Add custom validation, logging, etc.
    console.log('Sending notification:', request.message);
  },
  onAfterSend: async (request) => {
    // Log success, trigger webhooks, etc.
    console.log('Notification sent successfully');
  },
  onError: async (error, request) => {
    // Custom error handling
    console.error('Failed to send notification:', error);
  }
});

Custom Telegram Client

import { createTelegramClient } from 'nextjs-telegram-notify/server';

const client = createTelegramClient({
  botToken: process.env.TELEGRAM_BOT_TOKEN!,
  chatId: process.env.TELEGRAM_CHAT_ID!
});

await client.sendMessage('Custom message');
await client.sendDocument(fileAttachment, {
  caption: 'File caption'
});

📋 Use Cases

• ✅ Contact forms
• ✅ Bug reports
• ✅ Typo corrections
• ✅ User feedback & ratings
• ✅ Newsletter signups
• ✅ Order notifications
• ✅ Support tickets
• ✅ System alerts
• ✅ Analytics events
• ✅ Content moderation alerts

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Muhammad Abdugafarov

🙏 Acknowledgments

Built with ❤️ for the Next.js community.

Need help? Open an issue on GitHub