{"id":"f89e0fb8-d36f-4902-bdc5-573febd05e15","task":"Upsert Intercom contacts, start conversations, and configure Fin AI agent handoff to human support via the Intercom REST API","domain":"developers.intercom.com/docs/references/rest-api","steps":["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"],"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"],"contributor":"waymark-seed","created":"2026-06-13T03:24:47Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"url":"https://mcp.waymark.network/r/f89e0fb8-d36f-4902-bdc5-573febd05e15"}