---
title: Mentions | API Docs
description: Address a specific participant of a group chat with a mention, and read the mentions on messages you receive.
---

A mention addresses one participant of a [group chat](/channel/imessage/guides/chats/group-chats/index.md) by handle. Set `mention` on a text part of any send — `POST /v3/messages`, `POST /v3/chats`, or `POST /v3/chats/{chatId}/messages`. Mentions on messages you *receive* arrive on the text part as `mentions` — see [Receiving mentions](#receiving-mentions).

```
{
  "type": "text",
  "value": "Hey Kevin, can you confirm the address?",
  "mention": "+14155551234",
  "mention_range": [4, 9]
}
```

`mention` is the target’s handle — an E.164 phone number or Apple ID email — and it must belong to a current participant of the chat. `value` is the display text: use the bare name (`"Kevin"`, not `"@Kevin"`). `mention_range` is optional and narrows the highlight to a `[start, end)` slice of `value`; without it the whole `value` is highlighted.

Ranges are inclusive–exclusive and measured in UTF-16 code units, the same convention as [text decorations](/channel/imessage/guides/messaging/sending-messages#text-decorations/index.md). Most characters count as 1; some emoji count as 2.

## What the recipient sees

Rendering is per recipient, not per message. One send, two experiences:

| Recipient | Result                                                                                    |
| --------- | ----------------------------------------------------------------------------------------- |
| iMessage  | Highlighted mention, and the participant is notified **even if they have muted the chat** |
| RCS / SMS | The same text, delivered plain — no highlight, no mute override                           |

The chat’s service is not a constraint: a mention is accepted in any group, including one that mixes iMessage and RCS/SMS participants. Mixed groups simply get both rows of that table. See [Protocol Selection](/channel/imessage/guides/messaging/protocol-selection/index.md) for how the service per recipient is decided.

## Rules

- **Group chats only.** A mention in a direct chat is rejected with [`2023`](/channel/imessage/error/codes/2xxx/2023/index.md) — including a send to a single recipient, since that creates a direct chat.
- **One target per text part.** To mention two people, send two [text parts](/channel/imessage/guides/messaging/sending-messages#message-parts/index.md) — separated by a media part, or as separate messages, since consecutive text parts are not allowed.
- **The target must still be in the chat.** Mentioning a participant who was [removed](/channel/imessage/guides/chats/group-chats#managing-participants/index.md) returns `409` / [`2015`](/channel/imessage/error/codes/2xxx/2015/index.md); they can be added back and mentioned again. A handle that was never in the chat is a `400` / [`1004`](/channel/imessage/error/codes/1xxx/1004/index.md).
- **`mention` cannot be combined with `text_decorations` on the same part.** Put the decorated text in a different part.
- **`mention_range` requires `mention`**, and must satisfy `0 <= start < end <= len(value)`.

Everything above is a `400` / [`1004`](/channel/imessage/error/codes/1xxx/1004/index.md) except where noted.

## Reading mentions back

There is **no mention webhook event**. Mention data travels as a field on the text part itself, so any surface that returns message parts returns the mentions with them:

- `GET /v3/messages/{messageId}` and `GET /v3/chats/{chatId}/messages`
- The send response
- The [`message.sent`, `message.received`, `message.delivered`, and `message.read`](/channel/imessage/guides/webhooks/events#message-events/index.md) webhooks

```
{
  "type": "text",
  "value": "Kevin Dana one of you confirm the address?",
  "mentions": [
    { "handle": "+14155551234", "is_me": false, "range": [0, 5] },
    { "handle": "+14155559876", "is_me": true, "range": [6, 10] }
  ],
  "mention": "+14155551234",
  "mention_range": [0, 5]
}
```

`mentions` lists every mention on the part, in the order they appear in `value`, and is `null` on a part that carries no mention. `is_me` is whether the mentioned participant is the line reading the message — the same message reports `true` to the line that was named and `false` to everyone else, so it is the field to branch on when deciding whether you were addressed.

`mention` and `mention_range` are **deprecated on responses** and describe only the *first* mention on the part. They are positional, not personal: on the part above, a reader checking only `mention` concludes they were not mentioned. Read `mentions` instead. Both remain the way to **send** a mention.

## Receiving mentions

When a participant mentions your line in a group, the mention arrives on the text part of [`message.received`](/channel/imessage/guides/webhooks/events#message-events/index.md) and on every read surface above. Inbound differs from what you can send:

- **Several mentions per part.** A device puts every mention on the one text part it belongs to, so an inbound part can name two people — or the same person twice. Sends are still limited to one target per part.
- **iMessage only.** RCS and SMS have no way to mark a mention, so a message from an RCS or SMS participant arrives as plain text with `mentions` `null` — even in a group where other participants are on iMessage. Same split as [What the recipient sees](#what-the-recipient-sees), in the other direction.
- **Mentions and `text_decorations` can appear on the same part.** A sender’s device can apply both; the exclusion in [Rules](#rules) is a send-side constraint only.

## Related

- [Sending Messages](/channel/imessage/guides/messaging/sending-messages/index.md)
- [Group Chats](/channel/imessage/guides/chats/group-chats/index.md)
- [Webhook Events](/channel/imessage/guides/webhooks/events/index.md)
- [API Reference: Send Message](/channel/imessage/api/resources/chats/subresources/messages/methods/send/index.md)