Authenticate with an Intercom access token (Bearer scheme); confirm the token's scope includes conversations:write.
To assign a conversation to an admin or team, POST to /conversations/{conversation_id}/parts with a body containing type: assignment, assignee_id (admin or team ID), admin_id (the acting admin), and message_type: assignment.
To close a conversation, POST to /conversations/{conversation_id}/parts with message_type: close and the acting admin_id.
To snooze, open, or unassign a conversation, use the same manage endpoint with the appropriate message_type value (snoozed, open, or unassign).
To associate a company with a conversation for business context, PATCH the conversation resource and include the company identifier; this feature was introduced in a recent API update.
Subscribe to conversation webhooks (e.g., conversation.admin.assigned, conversation.admin.closed) to react to state changes in real time rather than polling.
Known gotchas
The assignee_id in an assignment request must be either an admin ID or a team ID; mixing up these two types (e.g., passing a team ID when the API expects an admin ID for that field) returns an opaque 422 error.
The Fin AI Agent's escalation outcome is represented in the API as resolution_state: escalated (previously routed_to_team in older API versions); code that checks the old enum value may misclassify escalated conversations.
Intercom enforces API version pinning via the Intercom-Version request header; omitting this header causes the API to use the account's default version, which may differ from the version you tested against and lead to unexpected field shapes.
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