# Overview

> Internal team notes on conversations and person profiles, with @mentions

The Notes API lets you create and manage **internal team notes**. Notes are only visible to your team — never to the contact. There are two kinds:

- **Conversation notes** — notes pinned to a conversation (a contact phone number on one of your Allo lines). They appear in the conversation timeline in the Allo apps.
- **Person notes** — notes on a person's CRM profile, addressed by the `per-*` `id` from the [People API](/docs/crm/people-overview). Under the hood, notes attach to the person's underlying contact record, which is what will allow company notes on a future `/v2/api/crm/companies/{id}/notes`.

## Note constraints

| Field | Constraint |
|-------|------------|
| `content` | Required. Non-blank, max 4,000 characters. |
| Mentions | Optional, inline in `content`. Max 15 per note. |
| Editing | Only the note's author can update or delete a note. |

## Mentions

Mention teammates inline in `content` using the syntax `@[Display Name](usr-xxxx)`:

```json
{
  "content": "Escalate to @[Jane Doe](usr-abc123) tomorrow"
}
```

- Get user IDs from [`GET /v2/api/users`](/docs/users/list-users) (requires the `USERS_READ` scope).
- Use `@[all](all)` to notify the whole team.
- A note or comment can contain at most **15 mentions**.
- Mentions with unknown user IDs are silently dropped — they render as plain text and notify no one.

Mentions trigger the **same notifications as the Allo apps**: the mentioned teammates receive a push notification, an email, and an entry in their in-app notification center.

<Note>
`@[all](all)` notifies every member of the team. Sent from an automation, this can get noisy fast — use it deliberately.
</Note>

Responses expose the parsed mentions as a structured array:

```json
{
  "mentions": [
    { "user_id": "usr-abc123", "name": "Jane Doe", "deleted": false }
  ]
}
```

`deleted` is `true` when the mentioned user has since been removed from the team.

Mentions work the same way in [thread comments](/docs/threads/overview).

## Webhooks

Subscribe to the `conversation_note.created`, `conversation_note.updated`, and `conversation_note.deleted` events for conversation notes, and `contact_note.created`, `contact_note.updated`, and `contact_note.deleted` for person notes. See the [Event catalog](/docs/webhooks/event-catalog#conversation_notecreated).

## Endpoints

### Conversation notes

<CardGroup cols={1}>
  <Card title="List conversation notes" href="/docs/notes/list-conversation-notes">
    All notes on a conversation, paginated
  </Card>
  <Card title="Create conversation note" href="/docs/notes/create-conversation-note">
    Add an internal note to a conversation
  </Card>
  <Card title="Get conversation note" href="/docs/notes/get-conversation-note">
    A single note by ID
  </Card>
  <Card title="Update conversation note" href="/docs/notes/update-conversation-note">
    Edit a note's content (author only)
  </Card>
  <Card title="Delete conversation note" href="/docs/notes/delete-conversation-note">
    Delete a note (author only)
  </Card>
</CardGroup>

### Person notes

<CardGroup cols={1}>
  <Card title="List person notes" href="/docs/notes/list-person-notes">
    All notes on a person's CRM profile, paginated
  </Card>
  <Card title="Create person note" href="/docs/notes/create-person-note">
    Add a note to a person's CRM profile
  </Card>
  <Card title="Update person note" href="/docs/notes/update-person-note">
    Edit a person note's content (author only)
  </Card>
  <Card title="Delete person note" href="/docs/notes/delete-person-note">
    Delete a person note (author only)
  </Card>
</CardGroup>
