📱 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

🙏 Acknowledgments

Built with ❤️ for the Next.js community.

Need help? Open an issue on GitHub

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github		.github
examples/basic		examples/basic
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
TESTING.md		TESTING.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

License

dev-muhammad/nextjs-telegram-notify

Folders and files

Latest commit

History

Repository files navigation

📱 nextjs-telegram-notify

✨ Features

📦 Installation

🚀 Quick Start

1. Set up your Telegram Bot

2. Add Environment Variables

3. Create API Route

4. Use in Your Components

📚 Usage Examples

Contact Form

Bug Report Button

File Upload

Server-Side Usage

Security Features

Rate Limiting

CORS Configuration

Security Best Practices

🔧 API Reference

useTelegramNotify(config?)

sendTelegramNotification(options)

Utility Functions

createNotification(options)

🎨 Message Formatting

HTML Format

Markdown Format

🔒 Security Best Practices

🛠️ Advanced Configuration

Custom API Route with Hooks

Custom Telegram Client

📋 Use Cases

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Languages

`useTelegramNotify(config?)`

`sendTelegramNotification(options)`

`createNotification(options)`