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

# Working with notes

> Get a webhook when a user mentions your agent in a note on a thread, and reply with a note of your own.

<img src="https://mintcdn.com/plain/ROgZ-q7f4CoulDd_/public/images/build-agent-triage.png?fit=max&auto=format&n=ROgZ-q7f4CoulDd_&q=85&s=edd571b9fcfaad48a33f0c316a82411d" alt="Triage agent" width="2400" height="1250" data-path="public/images/build-agent-triage.png" />

Notes are internal comments on a thread. A user can mention your agent in a note to hand it a question about that thread, and your agent can answer with a note.

Notes are never shown to the customer.

To work with notes, your machine user's API key needs `note:create` permissions as well as `thread:read` and `customer:read` to read the thread.

## Get notified when you're mentioned

Subscribe your [webhook target](/docs/webhooks) to [`thread.note_mention_created`](/docs/webhooks/thread-note-mention-created).

It fires when a note mentions a machine user, including when a user edits a note to add the mention. The payload has the `thread`, the `note`, and `mentions`, the list of machine users mentioned.

Check that your agent is among them:

```ts theme={null}
if (event.payload.eventType === "thread.note_mention_created") {
  const mentioned = event.payload.mentions.some(
    (machineUser) => machineUser.id === process.env.AGENT_MACHINE_USER_ID,
  );
  if (!mentioned) return;

  await runAgent(event.payload.thread, event.payload.note);
}
```

`note.markdown` holds what the user wrote. Mentions appear in it as tokens: `<@mu_…>` for a machine user and `<@u_…>` for a user. Only machine users are listed in `mentions`; strip or resolve the tokens before you pass the text to a model.

To see every note on a thread, not only the ones that mention you, subscribe to [`thread.note_created`](/docs/webhooks/thread-note-created) as well. It fires for your own notes too, so skip notes where `note.createdBy.actorType` is `machineUser` and `machineUserId` is yours.

## Reply with a note

The `createNote` mutation adds a note to the thread under the machine user's name. Send `text` as the plain version and `markdown` for formatting. To mention the user who asked, put their `<@u_…>` token in `markdown`; Plain renders it as a mention and notifies them.

```ts theme={null}
const author = event.payload.note.createdBy;
const mention = author.actorType === "user" ? `<@${author.userId}> ` : "";

const result = await plain.mutation.createNote({
  input: {
    customerId: event.payload.thread.customer.id,
    threadId: event.payload.thread.id,
    text: "The invoice failed because the card was declined on 3 September.",
    markdown: `${mention}The invoice failed because the card was **declined** on 3 September.`,
  },
});

if (result.error) throw new Error(result.error.message);
```

Notes have a maximum length of 10k characters. See [notes](/docs/graphql/notes) for updating and deleting.

Notes also work without a mention. An agent that triages threads can leave what it found as a note, and an agent that [hands off](/docs/agents/threads#hand-off) can use notes to say why it's handing off.