Notes

Create, update, and delete internal operator notes on chat sessions. Notes are private annotations visible only to operators — they are never sent to external channels or customers.

Overview

Notes are internal messages attached to a session. They appear as amber-colored bubbles in the chat interface and are distinguished from regular messages.

Each note supports an AI visibility flag (isNoteVisibleToAi). When enabled, the note content is included in the AI agent's conversation context, allowing you to give the AI additional instructions or context without the customer seeing it.

Create Note

Creates a new note on a session.

POST /channels/{channelId}/sessions/{sessionId}/agent-messages

Path Parameter	Description
channelId	The channel ID (find it in Settings → Channels → Channel ID)
sessionId	The session/conversation ID

Request Parameters

Field	Type	Required	Description
content	string	Yes	The note text (max 10,000 characters)
isNote	boolean	Yes	Must be true to create a note
isNoteVisibleToAi	boolean	No	Whether the AI agent can see this note (default: false)

Example Request

curl -X POST "https://api.maiacompany.io/channels/CHANNEL_ID/sessions/SESSION_ID/agent-messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Customer prefers communication in Portuguese. Follow up next week.",
    "isNote": true,
    "isNoteVisibleToAi": true
  }'

Response

Returns 200 OK with the created note:

{
  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "agentId": "agent-uuid",
  "role": "assistant",
  "content": "Customer prefers communication in Portuguese. Follow up next week.",
  "timestamp": 1704067200000,
  "isNote": true,
  "isNoteVisibleToAi": true,
  "isNewSession": false
}

TIP

This uses the same endpoint as From Human messages. The isNote: true flag is what distinguishes a note from a regular message.

Update Note

Updates an existing note's content and/or AI visibility.

PATCH /channels/{channelId}/sessions/{sessionId}/notes/{messageId}

Path Parameter	Description
channelId	The channel ID (find it in Settings → Channels → Channel ID)
sessionId	The session/conversation ID
messageId	The note's message ID

Request Parameters

Field	Type	Required	Description
content	string	Yes	The updated note text (max 10,000 characters)
isNoteVisibleToAi	boolean	No	Whether the AI agent can see this note

Example Request

curl -X PATCH "https://api.maiacompany.io/channels/CHANNEL_ID/sessions/SESSION_ID/notes/MESSAGE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated: Customer confirmed meeting for Thursday at 3pm.",
    "isNoteVisibleToAi": true
  }'

Response

Returns 200 OK with the updated note:

{
  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "content": "Updated: Customer confirmed meeting for Thursday at 3pm.",
  "isNoteVisibleToAi": true
}

Delete Note

Permanently deletes a note from a session.

DELETE /channels/{channelId}/sessions/{sessionId}/notes/{messageId}

Path Parameter	Description
channelId	The channel ID (find it in Settings → Channels → Channel ID)
sessionId	The session/conversation ID
messageId	The note's message ID

Example Request

curl -X DELETE "https://api.maiacompany.io/channels/CHANNEL_ID/sessions/SESSION_ID/notes/MESSAGE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Returns 200 OK:

{
  "message": "Note deleted successfully"
}

Webhook Events

Note operations trigger webhook events that you can subscribe to:

Event Type	Trigger
note_created	A new note is created
note_updated	A note's content is edited
note_deleted	A note is deleted

All note webhook payloads include messageId, sessionId, channelId, and operator info.

Note webhooks are configured through the Webhook Center (Settings → Webhooks), the same place as CRM webhooks. See CRM Webhooks for setup instructions and payload details.

Error Responses

Status	Description
400	Missing path parameters, empty content, or content too long
401	Invalid or missing authentication token
403	Note belongs to a different account
404	Note not found
500	Internal server error

WARNING

Only messages created as notes (isNote: true) can be updated or deleted via the notes endpoints. Attempting to update or delete a regular message will return a 400 error.