Retrieve the conversation ID from a webhook event or by searching: POST /conversations/search with filters on contact or timeframe.
To reply to a conversation, POST to /conversations/{conversation_id}/reply with a JSON body containing 'message_type': 'comment', 'type': 'admin', 'admin_id': {your_admin_id}, and 'body' (HTML or plain text).
To assign the conversation to a team, PUT to /conversations/{conversation_id}/parts with 'type': 'admin', 'assignee_id': the team ID, and 'admin_id': the admin performing the assignment.
To assign to a specific admin, use the same endpoint with 'assignee_id' set to the admin's ID — fetch admin IDs via GET /admins.
To close a conversation, include 'message_type': 'close' in the reply body rather than a separate close action.
Confirm the response contains an updated conversation object with the new 'state' and latest 'conversation_parts' entry reflecting your action.
Known gotchas
Intercom conversations have a 'state' (open, closed, snoozed) — replying to a closed conversation automatically reopens it, which may trigger unwanted automation rules; check state before replying.
The 'admin_id' in the reply body must be a real admin in the workspace — bot or system actions require using an actual admin ID; there is no anonymous system reply type.
Attaching files to a conversation reply via API is not supported in the basic reply endpoint; file attachments require the Intercom Messenger SDK or manual upload via a separate attachment flow.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp