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-*idfrom the People API. 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):
{
"content": "Escalate to @[Jane Doe](usr-abc123) tomorrow"
}
- Get user IDs from
GET /v2/api/users(requires theUSERS_READscope). - 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.
Responses expose the parsed mentions as a structured array:
{
"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.
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.
Endpoints
Conversation notes
All notes on a conversation, paginated
Add an internal note to a conversation
A single note by ID
Edit a note's content (author only)
Delete a note (author only)
Person notes
All notes on a person's CRM profile, paginated
Add a note to a person's CRM profile
Edit a person note's content (author only)
Delete a person note (author only)