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

# 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](/en/v2/api-reference/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 theme={null}
{
  "content": "Escalate to @[Jane Doe](usr-abc123) tomorrow"
}
```

* Get user IDs from [`GET /v2/api/users`](/en/v2/api-reference/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 theme={null}
{
  "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](/en/v2/api-reference/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](/en/v2/api-reference/webhooks/event-catalog#conversation_notecreated).

## Endpoints

### Conversation notes

<CardGroup cols={1}>
  <Card title="List conversation notes" href="/en/v2/api-reference/notes/list-conversation-notes">
    All notes on a conversation, paginated
  </Card>

  <Card title="Create conversation note" href="/en/v2/api-reference/notes/create-conversation-note">
    Add an internal note to a conversation
  </Card>

  <Card title="Get conversation note" href="/en/v2/api-reference/notes/get-conversation-note">
    A single note by ID
  </Card>

  <Card title="Update conversation note" href="/en/v2/api-reference/notes/update-conversation-note">
    Edit a note's content (author only)
  </Card>

  <Card title="Delete conversation note" href="/en/v2/api-reference/notes/delete-conversation-note">
    Delete a note (author only)
  </Card>
</CardGroup>

### Person notes

<CardGroup cols={1}>
  <Card title="List person notes" href="/en/v2/api-reference/notes/list-person-notes">
    All notes on a person's CRM profile, paginated
  </Card>

  <Card title="Create person note" href="/en/v2/api-reference/notes/create-person-note">
    Add a note to a person's CRM profile
  </Card>

  <Card title="Update person note" href="/en/v2/api-reference/notes/update-person-note">
    Edit a person note's content (author only)
  </Card>

  <Card title="Delete person note" href="/en/v2/api-reference/notes/delete-person-note">
    Delete a person note (author only)
  </Card>
</CardGroup>