Allo

Overview

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

Updated on

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

FieldConstraint
contentRequired. Non-blank, max 4,000 characters.
MentionsOptional, inline in content. Max 15 per note.
EditingOnly 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 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.

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

Person notes