VX Agents

OpenAPI Marketplace · Customer Support

Intercom Conversations & Contacts

v1.0.0 · 16 endpoints · 0 connections · shared by vx.ai

Lets an agent triage an Intercom support inbox: search and read conversations, reply as an admin, assign, tag, snooze or close them, and find, create or update the contacts behind them. Curated from Intercom's official OpenAPI specification.

Connect this API to an AI agent Browse all specs

What you can do with Intercom Conversations & Contacts via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /me getCurrentAdmin Show the admin and workspace this token acts as
GET /admins listAdmins List the teammates (admins) in the workspace
GET /teams listTeams List the teams conversations can be assigned to
GET /tags listTags List all tags in the workspace
POST /conversations/search searchConversations Search conversations by state, assignee, tag, date or text
GET /conversations listConversations List recent conversations, newest first
GET /conversations/{conversation_id} getConversation Get a conversation with its full message history
POST /conversations/{conversation_id}/reply replyToConversation Reply to a customer or add an internal note to a conversation
POST /conversations/{conversation_id}/parts manageConversation Assign, snooze, close or reopen a conversation
POST /conversations/{conversation_id}/tags tagConversation Add a tag to a conversation
POST /contacts/search searchContacts Search contacts by email, name, phone or custom attribute
GET /contacts/{contact_id} getContact Get a contact's profile and attributes
PUT /contacts/{contact_id} updateContact Update a contact's name, email, phone or attributes
POST /contacts createContact Create a new user or lead contact
GET /contacts/{contact_id}/notes listContactNotes List internal notes on a contact
POST /contacts/{contact_id}/notes addContactNote Add an internal note to a contact

Authentication

bearerAuth

Bearer token — sent as Authorization: Bearer <token>

Intercom access token sent as Authorization: Bearer <token>.

How to get a credential

  1. Sign in to Intercom and open the Developer Hub.
  2. Click New app, name it (e.g. "VX Agents") and pick the workspace.
  3. Open Configure > Authentication and copy the Access token. It acts for your workspace as the app.
  4. For apps installed on other workspaces, use OAuth instead and pass the resulting access token.

Permissions used

Permission (app settings) Operations
Read admins getCurrentAdmin, listAdmins, listTeams
Read conversations searchConversations, listConversations, getConversation
Write conversations replyToConversation, manageConversation, tagConversation
Read and list users and companies searchContacts, getContact, listContactNotes
Write users and companies createContact, updateContact, addContactNote
Read tags listTags

Common errors

  • 401 Unauthorized: token missing, mistyped or revoked. Copy it again from the Developer Hub.
  • 403 Forbidden (token_unauthorized/api_plan_restricted): the app lacks the permission above, or your plan does not include the endpoint. Enable the permission and reinstall the app.
  • 400 / 422: invalid body, e.g. a reply without admin_id, or an unknown contact role. Check the field names.
  • 429 Too Many Requests: rate limit (about 1,000 calls per minute per app). Wait for X-RateLimit-Reset and retry.
  • EU or AU workspaces must use https://api.eu.intercom.io or https://api.au.intercom.io.

Store the token as a VX Agents credential (Bearer token); it is never shown to the model.

Usage guide

Setup

  • Credential: an Intercom access token (Developer Hub > your app > Authentication), stored as a Bearer credential.
  • Call getCurrentAdmin once and pin the returned admin id as a preset admin_id. Every reply, note, assignment and tag needs it.
  • The Intercom-Version header is fixed at 2.11. EU/AU workspaces need the regional base URL (api.eu.intercom.io / api.au.intercom.io).

Triage the support inbox

  1. searchConversations with a query, e.g. {"query": {"operator": "AND", "value": [{"field": "state", "operator": "=", "value": "open"}, {"field": "admin_assignee_id", "operator": "=", "value": "0"}]}} for open, unassigned ones. Add pagination.per_page (max 150).
  2. getConversation to read the full thread (conversation_parts) and see who the customer is.
  3. searchContacts (e.g. field email) or getContact for the customer's profile; listContactNotes for past context.
  4. replyToConversation with message_type: "comment" (visible to the customer) or "note" (internal), type: "admin", admin_id and body (HTML allowed).
  5. manageConversation to change state: {"message_type": "assignment", "type": "admin", "admin_id": ..., "assignee_id": <admin or team id>}, "close", "snooze" (with snoozed_until Unix time) or "open".
  6. tagConversation with the tag id from listTags and admin_id.
  7. New or changed customer details: createContact (role = user or lead, plus email/phone/name) or updateContact. Use addContactNote to leave context.

Confirm before writing: a comment reply is sent to the customer right away, and contact updates change customer data. Show the user the reply text or the change and get a yes before calling replyToConversation (comment), createContact or updateContact. Internal notes, tags and assignments are fine without asking unless the user said otherwise.

Good to know

  • Timestamps are Unix seconds (created_at, updated_at, snoozed_until).
  • Conversation and contact ids are strings; teams and admins share the assignee id space (listTeams, listAdmins).
  • Search operators: =, !=, IN, NIN, <, >, ~ (contains), ^ (starts with). Nest up to 2 levels of AND/OR.
  • Paginate with pagination.starting_after from the previous response.
  • Rate limit is about 1,000 requests per minute per app (429 when exceeded).

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Intercom Conversations & Contacts” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs

  • Front Shared Inbox — Lets an agent work a Front shared inbox: list and search conversations, read messages and internal comments, look up co…
  • Jira Service Management — Lets an agent run a Jira Service Management help desk: find service desks, request types and queues, raise and look up …
  • Zendesk Support Tickets — Lets an agent run a Zendesk Support queue: search and list tickets, read the conversation, create tickets, and update s…
  • HubSpot Service Tickets — Find, read, create and update support tickets in HubSpot Service Hub: search tickets by status, owner, priority or any …