Mention a Human

Ping one specific person in a shared channel using their canonical identity

mention_user() turns a canonical human identity into the platform’s native @mention, so the right person gets a real ping in a shared channel.

Here’s a real example: a deploy agent posts in #deploys (Slack), where Alice, Bob and the bot are all members. Bob is on call:

Agent in #deploys (Slack, Alice + Bob + bot):
  (agent runs the pipeline, Bob is the on-call)
  await bot.adapter.send_message("#deploys",
      f"{bot.adapter.mention_user('bob')} prod deploy finished — please verify")

Slack renders:
  "@Bob prod deploy finished — please verify"
Bob gets a real notification; Alice sees the message without a ping.

Quick Start

1. Mention someone by canonical id

   Link the human once in an identity resolver, then pass the same resolver to Bot. Once the bot starts, bot.adapter.mention_user("alice") returns the native markup.

   from praisonaiagents import Agent
   from praisonaiagents.session import InMemoryIdentityResolver
   from praisonai_bot.bots import Bot
   
   resolver = InMemoryIdentityResolver()
   resolver.link("discord", "222", "alice")
   
   agent = Agent(name="deployer", instructions="Report deploy results")
   bot = Bot("discord", agent=agent, identity_resolver=resolver)
   
   # Once the bot is running:
   text = f"{bot.adapter.mention_user('alice')} your deploy finished"
   await bot.adapter.send_message(channel_id, text)   # -> "<@222> your deploy finished"

2. Fallback when the person isn't linked here

   If the person has no link on this platform, you get the id back as plain text. Your message still goes out; it just doesn’t ping anyone.

   resolver.link("telegram", "111", "carol")       # carol is only paired on Telegram
   
   bot.adapter.mention_user("carol")               # -> "carol" (plain text on Discord)

3. Use the unlinked platform:id shortcut

   If you already know this platform’s native id, pass "{platform}:{native_id}". The bot skips the resolver.

   from praisonai_bot.bots import DiscordBot
   
   bot = DiscordBot(token="...")
   bot.mention_user("discord:333")                 # -> "<@333>"
   bot.mention_user("slack:U1")                    # -> "slack:U1" (wrong platform, plain text)

How It Works

1. If the platform has no mention template, it can’t ping by id, so the id comes back as plain text.
2. A "{platform}:{native_id}" id whose prefix matches this adapter is rendered directly. The resolver isn’t called.
3. Otherwise the adapter calls links_for() on its identity resolver. Bot, BotOS and the gateway attach the resolver automatically.
4. The adapter uses the link for its own platform to render the mention, for example <@222>.
5. If there’s no link for this platform, or the lookup raises, the id comes back as plain text. A lookup error is logged as a warning and the reply is never lost.

Which form do I pass?

Configuration Options

There is nothing to configure: mention_user(unified_user_id) takes a single argument and returns a string. Full API: Bots SDK reference.

Common Patterns

Handoff ping

await bot.adapter.send_message(channel_id, f"{bot.adapter.mention_user(assignee)} please review PR #42")

Approval request

await bot.adapter.send_message(channel_id, f"{bot.adapter.mention_user(owner)} approve or reject this deploy")

Multi-recipient alert

on_call = ["alice", "bob"]
pings = " ".join(bot.adapter.mention_user(uid) for uid in on_call)
await bot.adapter.send_message(channel_id, f"{pings} error rate above 5%")

Best Practices