> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Mention a Human"
        A[📝 agent writes<br/>mention_user alice] --> B[🧠 identity resolver<br/>links_for]
        B --> C[💬 native markup<br/>per platform]
        C --> D[🔔 human notified]
    end
    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    class A input
    class B,C process
    class D output
```

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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant Bot as 🤖 Bot (Slack/Discord)
    participant Resolver as 🪪 IdentityResolver
    participant Platform
    participant Human

    Agent->>Bot: mention_user("alice")
    Bot->>Resolver: links_for("alice")
    Resolver-->>Bot: [IdentityLink(platform="discord", platform_user_id="222")]
    Bot-->>Agent: "<@222>"
    Agent->>Bot: send_message("<@222> your deploy finished")
    Bot->>Platform: deliver with native mention
    Platform-->>Human: 🔔 ping
```

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.

| Platform | Native mention | Falls back to text? |
| - | :-: | :-: |
| Slack | ✅ `<@U123>` | — |
| Discord | ✅ `<@222>` | — |
| Telegram | ❌ (no template) | ✅ plain id |
| WhatsApp | ❌ (no template) | ✅ plain id |

### Which form do I pass?

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start[Which form do I pass?] --> Q1{Is the human<br/>paired on all platforms?}
    Q1 -->|Yes| Canon["bot.adapter.mention_user('alice')<br/>canonical id"]
    Q1 -->|No| Q2{Do I know this<br/>platform's native id?}
    Q2 -->|Yes| Prefixed["bot.adapter.mention_user('discord:333')<br/>platform:native shortcut"]
    Q2 -->|No| Fallback[Fallback: name string renders as plain text]
    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef a fill:#10B981,stroke:#7C90A0,color:#fff
    class Q1,Q2,Start q
    class Canon,Prefixed,Fallback a
```

***

## 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](https://praison.ai/docs/sdk/reference/praisonaiagents/modules/bots.md).

***

## Common Patterns

**Handoff ping**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
await bot.adapter.send_message(channel_id, f"{bot.adapter.mention_user(assignee)} please review PR #42")
```

**Approval request**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
await bot.adapter.send_message(channel_id, f"{bot.adapter.mention_user(owner)} approve or reject this deploy")
```

**Multi-recipient alert**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

> [accordion] Prefer canonical ids over raw native ids
>
> Pass `"alice"`, not `"222"`. The same agent code then works unchanged on Slack, Discord, or any other channel.

> [accordion] The plain-text fallback is a feature
>
> If someone isn't paired on this platform, they're named in plain text. The message is still delivered and nothing crashes.

> [accordion] Pair the human first
>
> A canonical id only becomes a native mention after it's linked. See [Bot Pairing](https://praison.ai/docs/features/bot-pairing.md) to set up the links.

> [accordion] Don't write raw \<@id> markup yourself
>
> Let `mention_user()` produce the markup. Each adapter owns its template, so you can swap platforms without changing your code.

***

## Related

> [card] [Bot Pairing](https://praison.ai/docs/features/bot-pairing.md)
>
> How a human becomes a canonical identity

> [card] [Identity Canonicalization](https://praison.ai/docs/features/gateway-identity-canonicalization.md)
>
> The identity map the resolver reads

> [card] [Implicit Mentions](https://praison.ai/docs/features/bot-implicit-mentions.md)
>
> The inbound counterpart

> [card] [Bot Gateway](https://praison.ai/docs/features/bot-gateway.md)
>
> Where channel adapters are wired


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.