VX Agents

API directory · Customer Support

Intercom Tickets

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

For support teams that track refunds, bugs and back-office requests as Intercom tickets: search the queue by state or assignee, open a ticket of the right ticket type for a customer, move it between ticket states, reassign it, tag it, and post a customer reply or an internal note.

Connect this API to an AI agent Browse all specs

What you can do with Intercom Tickets 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
POST /tickets/search searchTickets Search tickets by state, assignee, type, contact or dates
GET /tickets/{ticket_id} getTicket Get a ticket with its attributes, state and contacts
PUT /tickets/{ticket_id} updateTicket Change a ticket's state, assignee or attributes
POST /tickets createTicket Open a ticket of a ticket type for a customer
POST /tickets/{ticket_id}/reply replyToTicket Reply to the customer or add an internal note
POST /tickets/{ticket_id}/tags tagTicket Add a tag to a ticket
GET /ticket_types listTicketTypes List ticket types (customer, back-office, tracker)
GET /ticket_types/{ticket_type_id} getTicketType Get a ticket type with its attribute fields
GET /ticket_states listTicketStates List the ticket states a ticket can move through
GET /admins listAdmins List teammates to find an assignee or reply author id
GET /tags listTags List workspace tags to find a tag id

Authentication

intercom_token

Bearer token — sent as Authorization: Bearer <token>

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

How to get a credential

  1. Open the Intercom Developer Hub (https://app.intercom.com/a/apps/_/developer-hub) and create an app for your workspace.
  2. Open Configure > Authentication and copy the Access token (it acts on your own workspace). For other workspaces, use OAuth instead.
  3. Under Permissions, turn on the permissions in the table below and save.

Permissions used

Permission Operations
Read tickets searchTickets, getTicket, listTicketTypes, getTicketType, listTicketStates
Write tickets createTicket, updateTicket, replyToTicket, tagTicket
Read admins and teammates listAdmins
Read tags listTags

Common errors

Status Meaning Fix
401 Token missing or revoked Copy the access token again from the Developer Hub.
403 Permission missing Turn on the permission above for the app and save.
400 Bad ticket attributes or state Use attribute names from getTicketType and a ticket_state_id from listTicketStates.
404 Ticket not found Use the ticket id from searchTickets (not the ticket number shown to customers).
429 Rate limit Wait and retry; workspaces get roughly 10,000 calls per minute per app.

Workspaces hosted in the EU or Australia use https://api.eu.intercom.io or https://api.au.intercom.io. Store the token as a VX Agents credential (Bearer token).

Usage guide

Setup

  1. Add an Intercom access token (Developer Hub app) as a VX Agents Bearer credential, with read/write tickets, read admins and read tags permissions.
  2. Every call pins Intercom-Version: 2.17. EU or AU workspaces must change the base URL to https://api.eu.intercom.io or https://api.au.intercom.io.
  3. Worth pinning: your own admin_id (from listAdmins) for replies and updates.

Work the ticket queue

  1. listTicketTypes and listTicketStates once to learn type ids, their attribute names (getTicketType) and state ids (submitted, in_progress, waiting_on_customer, resolved categories).
  2. searchTickets with a query, e.g. {"field": "admin_assignee_id", "operator": "=", "value": "<admin id>"}; other fields include state, open, ticket_type_id, contact_ids, team_assignee_id, created_at. Combine with AND/OR; page with pagination.starting_after.
  3. getTicket for the full ticket: attributes, state, contacts and linked conversations.
  4. To open a ticket, confirm with the user, then createTicket with ticket_type_id, contacts: [{"id": "<contact id>"}] (or email) and ticket_attributes such as _default_title_ and _default_description_.
  5. To move or reassign it, confirm, then updateTicket with ticket_state_id, assignee_id, open: false to close, and admin_id (the teammate making the change).
  6. To answer, confirm the text, then replyToTicket with {"message_type": "comment", "type": "admin", "admin_id": "...", "body": "..."}. Use note for an internal note; tracker and unshared back-office tickets accept only notes.
  7. listTags then tagTicket with {"id": "<tag id>", "admin_id": "..."} to label it.

Good to know

  • Ticket id (used in paths) differs from ticket_id (the number customers see).
  • Timestamps are Unix seconds.
  • Search allows at most 2 nested filters and 15 filters per AND/OR group; 20 results per page by default.
  • Replies with comment reach the customer by email or Messenger, and state changes can trigger workflows: always confirm first. Deleting tickets and editing ticket types are not part of this spec.

Source: Intercom REST API 2.17 reference, Tickets, Ticket Types and Ticket States (https://developers.intercom.com/docs/references/rest-api/api.intercom.io/tickets), checked 2026-10-20.

How to use this spec

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

Related APIs