Authenticate with a Bearer token from an Intercom app access token against https://api.intercom.io
POST /contacts with role:user or role:lead, email, name, and custom_attributes to create or upsert a contact — Intercom deduplicates by email for user role contacts
POST /conversations with the contact's id as from.id, from.type=user, and a body to initiate an outbound conversation or inject a message into an existing thread
Configure Fin AI agent in the Intercom UI to handle inbound conversations; use the Conversations API to set conversation_rating and tag conversations Fin could not resolve for agent review
To hand off from Fin to a human, assign the conversation via PATCH /conversations/{id}/parts with type:assignment, assignee_id (teammate or team ID), and body message
GET /conversations/{id} to verify assignment and retrieve the full conversation part history, including Fin's automated responses, for context handoff
Known gotchas
Intercom deduplicates contacts by email only for user role — lead role contacts are not deduplicated and POSTing the same email multiple times creates multiple lead records; use search via POST /contacts/search before creating
Fin AI agent handoff via API requires that the conversation is in an active state; attempting to assign a closed or snoozed conversation via the API returns a 422 error — reopen the conversation first
The Conversations API rate limit is separate from the Contacts API rate limit; high-volume real-time operations (chat platforms) should monitor both limit headers independently
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