Mentions

In group chats, bots typically only respond when mentioned. This guide shows you how to handle mentions effectively.

How Mentions Work

Mention detection is crucial for group chat bots. In private chats, bots can respond to every message, but in group chats, bots should only respond when explicitly mentioned to avoid spamming the conversation. Understanding how mentions work helps you build bots that feel natural and respectful of group chat dynamics.

The mention system allows bots to distinguish between messages directed at them and general group conversation. This prevents bots from interrupting conversations and ensures they only participate when addressed.

In private chats: The bot always responds (no mention needed).

In group chats: The bot only responds when:

• The message starts with / (commands)
• The message contains the bot's handle (mentions)

Mention Detection

The adapter automatically detects mentions and sets the isMentioned flag on the message context. This flag is essential for building bots that behave appropriately in group chats—checking this flag allows you to filter messages and only respond when your bot is explicitly addressed. The mention detection works differently on each platform, but the unified API makes it easy to handle mentions consistently.

Using isMentioned is the recommended way to check if your bot should respond to a message. This flag is set automatically based on the platform's mention format and your bot's configured handle.

The adapter automatically sets ctx.message.isMentioned:

bot.on('message', async (ctx) => {
  if (ctx.message.isMentioned) {
    // Bot was mentioned in a group chat
    await ctx.bot.send({
      provider: ctx.provider,
      channel: ctx.channel.id,
      content: {
        type: 'text',
        content: 'Hey! You mentioned me!'
      }
    })
  }
})

Platform Differences

Different messaging platforms handle mentions differently, so understanding platform-specific behavior helps you configure your bot correctly. Telegram uses username-based mentions (@username), while WhatsApp uses keyword detection. These differences affect how you configure your bot's handle and how mentions are detected.

Knowing platform differences helps you set up your bot correctly and troubleshoot mention detection issues. Always test mention detection after configuring your bot's handle.

Handling Mentions

Proper mention handling ensures your bot responds appropriately in group chats while staying responsive in private chats. You can filter messages based on mention status, implement mention-based commands, or use middleware to handle mentions globally. Each approach has its use cases—choose the one that fits your bot's needs.

Understanding different mention handling patterns helps you build bots that feel natural and don't interrupt group conversations unnecessarily.

Complete Example

Here's a complete example that demonstrates proper mention handling in group chats. This example shows how to filter messages based on mention status, ensuring your bot only responds when explicitly addressed in groups while maintaining full responsiveness in private chats. It's a production-ready pattern you can adapt for your own bots.

This example demonstrates:

• Mention Filtering: Checking isMentioned before responding in groups
• Channel Type Detection: Different behavior for groups vs private chats
• Responsive Design: Full responsiveness in private chats
• Clean Integration: Simple integration with message event listeners

import { Bot, telegram } from '@igniter-js/bot'

const bot = Bot.create({
  id: 'mention-bot',
  name: 'Mention Bot',
  adapters: {
    telegram: telegram({
      token: process.env.TELEGRAM_TOKEN!,
      handle: '@mention_bot',
      webhook: {
        url: process.env.TELEGRAM_WEBHOOK_URL!
      }
    })
  },
  on: {
    message: async (ctx) => {
      // In groups, only respond to mentions
      if (ctx.channel.isGroup && !ctx.message.isMentioned) {
        return
      }
      
      if (ctx.message.content?.type === 'text') {
        await ctx.bot.send({
          provider: ctx.provider,
          channel: ctx.channel.id,
          content: {
            type: 'text',
            content: `Hello, ${ctx.message.author.name}!`
          }
        })
      }
    }
  }
})

await bot.start()

Best Practices

Proper mention handling ensures your bot responds appropriately in group chats while staying responsive in private chats. These practices help you build bots that feel natural and don't spam group conversations.