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

# Mentions

> Mention a group participant and read mentions by stable Contact ID.

A mention names one group participant inside a text part.

Set `mention` to the participant's handle, and write the display name in `value` without an at sign. `mention_range` is optional and selects the slice of `value` that the mention covers; without it, the mention covers the whole part. Count the range in UTF-16 code units, not visible characters: most characters are one unit, some emoji are two, and `0 <= start < end <= value.length` must hold in JavaScript.

Mentions work only in a group chat, and the target must still be a participant. Send the part through either [send path](/messages/send); nothing else about the request changes.

## Send a mention

Mention `echo` at the start of a request:

```json theme={null}
{
  "message": {
    "parts": [{
      "type": "text",
      "value": "Echo, summarize this",
      "mention": "echo",
      "mention_range": [0, 4]
    }]
  }
}
```

The send returns `202` with the message. When anyone reads it back, each text part carries `mentions`, ordered by position, or `null` when there are none.

Each entry has the participant's stable Contact `id`, their current handle, and the `range` it covers. `is_me` is `true` when the mention addresses the reader. The `range` covers the whole value when the send omitted `mention_range`.

Store the `id`, not the handle; a handle can be renamed. Branch on `is_me` rather than comparing handles. The response fields `mention` and `mention_range` are deprecated mirrors of the first entry.

## When it fails

| Status | Code                               | Cause                           | Next action                                    |
| ------ | ---------------------------------- | ------------------------------- | ---------------------------------------------- |
| `400`  | [1004](/api-reference/errors#1004) | The handle is not in this chat. | Use a current participant's handle.            |
| `409`  | [2023](/api-reference/errors#2023) | The chat is not a group.        | Send the mention in a group chat.              |
| `409`  | [2015](/api-reference/errors#2015) | The mentioned participant left. | Refresh participants and choose a current one. |

## Next steps

* [Send a message](/messages/send)
* [Read message history](/chats/history)
* [Receive webhooks](/webhooks)