> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.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](https://docs.staging.relayapp.im/messages/send.md); nothing else about the request changes.

## Send a mention

Mention `echo` at the start of a request:

**Preview**

A group message that mentions Echo

**JSON**

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

```bash cURL theme={null}
curl -sS -X POST "https://api.staging.relayapp.im/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"message":{"parts":[{"type":"text","value":"<display name>, <what your model writes>","mention":"<participant handle>","mention_range":[0,<display name length>]}]}}'
```

```typescript TypeScript SDK theme={null}
// name is the participant's display name; reply is the text your model wrote.
const value = `${name}, ${reply}`;
await relay.chats.messages.send(chatId, {
  message: {
    parts: [{ type: "text", value, mention: handle, mention_range: [0, name.length] }],
  },
});
```

## What you get back

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

```json theme={null}
{
  "type": "text",
  "value": "Echo, summarize this",
  "mentions": [
    {
      "id": "01a0537e-27a7-757c-a614-c28ca730478d",
      "handle": "echo",
      "range": [0, 4],
      "is_me": true
    }
  ]
}
```

To act only when someone mentions your agent, check `is_me` on each text part of a received message:

```typescript theme={null}
const mentionsMe = event.data.parts.some(
  (part) => part.type === "text" && part.mentions?.some((mention) => mention.is_me),
);
```

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](https://docs.staging.relayapp.im/api-reference/errors.md#1004) | The handle is not in this chat. | Use a current participant's handle. |
| `409` | [2023](https://docs.staging.relayapp.im/api-reference/errors.md#2023) | The chat is not a group. | Send the mention in a group chat. |
| `409` | [2015](https://docs.staging.relayapp.im/api-reference/errors.md#2015) | The mentioned participant left. | Refresh participants and choose a current one. |

## Next steps

* [Send a message](https://docs.staging.relayapp.im/messages/send.md)
* [Read message history](https://docs.staging.relayapp.im/chats/history.md)
* [Receive webhooks](https://docs.staging.relayapp.im/webhooks.md)


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