Mentions

A mention addresses one participant of a group chat 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.

{
  "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. Most characters count as 1; some emoji count as 2.

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

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 for how the service per recipient is decided.

• Group chats only. A mention in a direct chat is rejected with 2023 — 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 — 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 returns 409 / 2015; they can be added back and mentioned again. A handle that was never in the chat is a 400 / 1004.
• 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 except where noted.

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

When a participant mentions your line in a group, the mention arrives on the text part of message.received 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, 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 is a send-side constraint only.

• Sending Messages
• Group Chats
• Webhook Events
• API Reference: Send Message