/v1/conversations/{conversation_id}/notesstableAdd an internal note
- Needs
- Manage conversations: notes, assign, close, tags, reminders
(inbox:write) - Plan
- Any plan with API access
- Limits
- 60 a minute per key
- Dry run
- Yes — a full preview with ?dry_run=true
- Undo
- Notes can be deleted in the inbox. Notifications already sent to mentioned people stay.
Adds an internal note to a conversation for your team — a handover, a ticket link, a summary. Notes are never sent to the customer.
Mention colleagues with mention_staff_ids and/or mention_emails (up to 20 people; duplicates are ignored, emails match case-insensitively). Each person mentioned gets an in-app and push notification, and a conversation.mention.created event is sent for each. The note is then posted as a mention line in the conversation (at most 2000 characters), kind is mention and mentioned lists who was notified. Write {{staff_id}} in the text to place a mention inline; otherwise the mentioned people are listed before the text. Every person is checked first: if any id or email is not an active staff member of your workspace you can mention, the answer is 400 with reason: unknown_staff, errors[] points at each one, and nothing is added. You may mention yourself.
A note with mentions needs an Idempotency-Key header (a plain note does not): a retry then never notifies anyone twice. Try it with ?dry_run=true first: every check runs and the answer lists exactly who would be notified (mentioned), with note_id: null; nothing is written and nobody is notified.
Try it
Protects against doing it twice if you retry: a retry with the same key gets the first answer back instead of running again.
Code and response
curl -X POST 'https://mcp.wa-api.cloud/v1/conversations/77410/notes?dry_run=true' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"text": "Ticket #4411 opened in the helpdesk: https://help.example.com/tickets/4411"
}'The code reads your key from $API_KEY.
Parameters
| Field | Type | What it is |
|---|---|---|
| conversation_idrequired | string · path | The conversation id.pattern ^\d{1,19}$Signed in? Pick one from your data with “My data”. |
Body
| Field | Type | What it is |
|---|---|---|
| textrequired | string | The note (staff only): up to 5000 characters, or 2000 with mentions. {{staff_id}} places a mentioned person inline.1–5000 characters |
| mention_staff_ids | array of string | Mention these staff members by id (up to 20 people in total). Each is notified.1–20 items |
| mention_emails | array of string | Mention staff members by their login email (case-insensitive; up to 20 people in total).1–20 items |
Headers
| Field | Type | What it is |
|---|---|---|
| Authorizationrequired | header | Bearer $API_KEY — your API key. |
| Api-Version | header | The API version to use, e.g. 2026-10-01. Default: the version your key is pinned to.one of: 2026-10-01 · pattern ^\d{4}-\d{2}-\d{2}$ |
| Idempotency-Key | header | Any unique string (8–128 characters). A retry with the same key returns the first answer instead of running twice. Kept 24 hours.pattern ^[A-Za-z0-9._:-]+$ · 8–128 characters |
Response 201
The note was added.
| Field | Type | What it is |
|---|---|---|
| note_idrequired | string or null | The note id; with mentions, the id of the mention line in the thread. null in a dry run. |
| conversation_idrequired | string | |
| visible_to_customerrequired | boolean | always false |
| kindrequired | string | note = a plain internal note; mention = posted as a mention line that notified mentioned.one of: note, mention |
| mentionedrequired | array of object | Who was mentioned and notified (empty for a plain note); in a dry run, who would be. |
| staff_idrequired | string | |
| namerequired | string or null | |
| dry_run | boolean | true when this was a dry run: every check ran and nothing changed. |
Errors
Errors are application/problem+json. Branch on code.
| Status | Code | When |
|---|---|---|
| 400 | invalid_input | A field is missing or has the wrong format. |
| 401 | unauthenticated | The Authorization header is missing, the key is unknown, expired or revoked. |
| 403 | entitlement_required | The workspace's plan does not include API access ( |
| 403 | insufficient_scope | The key does not have the permission this operation needs. |
| 404 | not_found | No conversation with this id. |
| 409 | conflict | Also returned while a request with the same Idempotency-Key is still running. |
| 429 | rate_limited | The key or workspace went over its rate limit. Wait for |
| 503 | upstream_unavailable | A service behind the API is briefly unavailable. Safe to retry with backoff. |
| 504 | timeout | The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice. |
Examples
Link a helpdesk ticket
Request body
{
"text": "Ticket #4411 opened in the helpdesk: https://help.example.com/tickets/4411"
}Response 201
{
"note_id": "90331",
"conversation_id": "77410",
"visible_to_customer": false,
"kind": "note",
"mentioned": []
}Ask a colleague to take a look
Request body
{
"text": "{{1203}} can you approve the refund for this order?",
"mention_staff_ids": [
"1203"
],
"mention_emails": [
"finance@example.com"
]
}Response 201
{
"note_id": "5501240",
"conversation_id": "77410",
"visible_to_customer": false,
"kind": "mention",
"mentioned": [
{
"staff_id": "1203",
"name": "Priya Nair"
},
{
"staff_id": "1207",
"name": "Finance Team"
}
]
}Webhook events
These events can fire after this call. Subscribe an endpoint to hear about them.
Operation path
The same operation is also at POST /v1/ops/inbox_add_note, with every field in the JSON body.