Intercom
OfficialEnables AI systems to access Intercom conversations, contacts, and customer data.
Tools (13)
search_conversations
Search for Intercom conversations using multiple filter criteria. Supports filtering by: - IDs: Search for specific conversation IDs - Source: Filter by source type (email, chat, etc.), author name/email - State: Filter by conversation state (open, closed, snoozed) - Assignment: Filter by team assignee ID or admin assignee ID - Statistics: Filter by response times and assignment metrics - AI Agent: Filter by Fin AI agent participation and resolution state Pagination: - Results are paginated with up to 150 items per page (default 5) - If more results exist, the response includes a 'pages' object with 'pages.next.starting_after' cursor - To fetch the next page, make another request with the SAME search parameters plus the 'starting_after' value from the previous response - Continue until 'pages.next' is not present in the response Returns a list of matching conversations with basic details. Use get_conversation for full details.
get_conversation
Retrieve complete details for a specific Intercom conversation. Returns: - Full conversation metadata (state, priority, timestamps) - Complete message history with all conversation parts - Associated contacts and tags - Assignment and team information Accepted ID formats: - Raw conversation ID (e.g., 123456789) - Prefixed ID (e.g., conversation_123456789) - Intercom URL (e.g., https://app.intercom.com/a/inbox/_/inbox/conversation/123456789) Tip: If you copied the ID from a search or fetch result, remove the 'conversation_' prefix. This tool also accepts the prefixed form and URLs and will normalize automatically. Use this after search_conversations to get full conversation content.
search_contacts
Search for Intercom contacts using multiple filter criteria. Supports filtering by: - IDs: Search for specific contact IDs - Email/Domain: Filter by email address or domain - Name/Phone: Search by contact name or phone number - Custom Attributes: Filter by any custom data fields Pagination: - Results are paginated with up to 150 items per page (default 5) - If more results exist, the response includes a 'pages' object with 'pages.next.starting_after' cursor - To fetch the next page, make another request with the SAME search parameters plus the 'starting_after' value from the previous response - Continue until 'pages.next' is not present in the response Returns a list of matching contacts with their attributes. Use get_contact for additional details.
get_contact
Retrieve complete details for a specific Intercom contact. Returns: - Full contact profile (name, email, phone, location) - Role and signup information - Custom attributes and metadata - Last seen and activity timestamps Accepted ID formats: - Raw contact ID (UUID) - Prefixed ID (e.g., contact_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee) - Intercom URL (e.g., https://app.intercom.com/a/apps/_/users/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee) Tip: If you copied the ID from a search or fetch result, remove the 'contact_' prefix. This tool also accepts the prefixed form and URLs and will normalize automatically. Use this after search_contacts to get full contact information.
list_companies
List Intercom companies with optional filters. Supports: - name: Find a company by exact name match (returns a single company) - company_id: Find a company by its external company_id (returns a single company) - tag_id: Filter companies by tag ID - segment_id: Filter companies by segment ID Pagination: - Uses page-based pagination (not cursor-based) - Default: page 1, 15 companies per page (max 60) - Set 'per_page' (1-60) and 'page' to navigate results - Response includes total_count and pages with total_pages Note: name and company_id are exact-match lookups that return a single company. For browsing all companies, omit name and company_id and paginate through results. Use get_company for full details including all custom_attributes.
get_company
Retrieve complete details for a specific Intercom company. Returns: - Full company profile (name, company_id, plan, industry, size) - Monthly spend and user count - All custom_attributes with their values (critical for attribute auditing) - Associated segments and tags - Activity timestamps (remote_created_at, last_request_at) Accepted ID formats: - Raw company ID - Prefixed ID (e.g., company_abc123def456) - Intercom URL (e.g., https://app.intercom.com/a/apps/_/companies/abc123def456) Tip: If you copied the ID from a search or fetch result, remove the 'company_' prefix. This tool also accepts the prefixed form and URLs and will normalize automatically. Use this after list_companies to get full company information including all custom attributes.
search
Purpose: 1. Search for resources in Intercom (conversations and contacts) using a unified query approach. For companies, use the list_companies tool. 2. Note that only a subset of properties will be returned in search results. 3. For complete details, use the Fetch tool with the returned IDs. Usage: 1. MUST specify object_type:conversations OR object_type:contacts to indicate which API to call. 2. Use specific field searches for precise filtering (e.g., email:john@example.com). 3. Use the starting_after parameter for pagination when more results exist. 4. Combine multiple search criteria with logical operators for complex queries. Search Tool Response: 1. Returns results with id, title, text, and url for each match. 2. IDs are prefixed with 'conversation_' or 'contact_' to indicate type. 3. Use these IDs with the Fetch tool to get complete resource details. Note: When filtering by id/contact_ids in queries, provide raw IDs without prefixes. If you pass prefixed IDs to get_conversation/get_contact, they are accepted and normalized. Intercom Search Query DSL specification: • Tokens separated by spaces • Each token: key[:op]:value • op (optional; default "eq") ∈ { eq, neq, gt, gte, lt, lte, in, nin, contains } • value: unquoted (alphanumeric, no spaces) or quoted in single/double quotes (to include spaces) Common Parameters: – object_type (mandatory) → "conversations" or "contacts" (specifies which API to call) – q/query → free-text search across key fields – created_at/updated_at → timestamp filters (YYYY-MM-DD or Unix timestamp) – limit → max results (default 10, max 150) – starting_after → pagination cursor CONVERSATION SEARCH (object_type:conversations): Supported fields: – id → raw conversation ID (no 'conversation_' prefix) – state → conversation state ("open", "closed", "snoozed") – priority → conversation priority ("priority", "not_priority") – open → boolean indicating if conversation is open (true/false) – read → boolean indicating if conversation has been read (true/false) – waiting_since → timestamp indicating how long conversation has been waiting (Unix timestamp) – snoozed_until → timestamp until which conversation is snoozed (Unix timestamp) – created_at → timestamp when conversation was created (Unix timestamp or YYYY-MM-DD) – updated_at → timestamp of last update (Unix timestamp or YYYY-MM-DD) Source fields: – source_type → conversation source type ("conversation", "email", "facebook", "twitter", etc.) – source_id → identifier for the source – source_delivered_as → delivery method of the source – source_subject → subject line of the conversation – source_body → body content of the conversation – source_url → URL associated with the source – source_author_id → identifier of the author – source_author_type → type of author (e.g., "user", "admin") – source_author_name → name of the message author – source_author_email → email of the message author Assignment fields: – contact_ids → raw contact IDs (UUIDs) associated with the conversation (no 'contact_' prefix) – teammate_ids → identifiers of teammates involved – team_assignee_id → team ID assigned to the conversation – admin_assignee_id → admin ID assigned to the conversation – tag_ids → identifiers of tags associated with the conversation Channel: – channel_initiated → channel through which conversation was initiated Statistics fields: – statistics_time_to_assignment → time to assignment in seconds – statistics_time_to_admin_reply → time to admin reply in seconds – statistics_time_to_first_close → time to first close in seconds – statistics_time_to_last_close → time to last close in seconds – statistics_median_time_to_reply → median time to reply in seconds – statistics_first_contact_reply_at → timestamp of first contact reply – statistics_first_assignment_at → timestamp of first assignment – statistics_first_admin_reply_at → timestamp of first admin reply – statistics_first_close_at → timestamp of first close – statistics_last_assignment_at → timestamp of last assignment – statistics_last_assignment_admin_reply_at → timestamp of last assignment admin reply – statistics_last_contact_reply_at → timestamp of last contact reply – statistics_last_admin_reply_at → timestamp of last admin reply – statistics_last_close_at → timestamp of last close – statistics_last_closed_by_id → identifier of last person who closed the conversation – statistics_count_reopens → number of times conversation was reopened – statistics_count_assignments → number of times conversation was assigned – statistics_count_conversation_parts → number of parts in the conversation Rating fields: – conversation_rating_requested_at → timestamp when rating was requested – conversation_rating_replied_at → timestamp when rating was replied to – conversation_rating_score → score given in the rating – conversation_rating_remark → remarks given in the rating – conversation_rating_contact_id → identifier of contact who provided the rating – conversation_rating_admin_id → identifier of admin associated with the rating AI Agent fields: – ai_agent_participated → boolean indicating if Fin AI agent participated (true/false) – ai_agent_resolution_state → AI agent resolution state – ai_agent_last_answer_type → AI agent last answer type – ai_agent_rating → AI agent rating score – ai_agent_rating_remark → AI agent rating remark – ai_agent_source_type → AI agent source type – ai_agent_source_title → AI agent source title CONTACT SEARCH (object_type:contacts): Supported fields: – id → raw contact ID (UUID, no 'contact_' prefix) – name → contact name – email → contact email address – email_domain → email domain – phone → contact phone number – role → contact role ("user", "lead") – custom_attributes.* → any custom attribute field (e.g., custom_attributes.company) EXAMPLES: user: show me recent conversations query: object_type:conversations created_at:gt:1735689600 user: find open conversations from email query: object_type:conversations state:open source_type:email user: search for conversations from support emails query: object_type:conversations source_author_email:contains:"@support" user: find conversations with slow response times query: object_type:conversations statistics_time_to_admin_reply:gt:3600 user: find conversations about billing query: object_type:conversations source_subject:contains:"billing" user: find conversations mentioning refund query: object_type:conversations source_body:contains:"refund" user: find contacts named John query: object_type:contacts name:"John" user: find contacts from example.com domain query: object_type:contacts email_domain:"example.com" user: find contacts with specific custom attribute query: object_type:contacts custom_attributes.plan_status:"active" user: recent contact activity query: object_type:contacts updated_at:gt:1735689600 limit:50 user: find conversations for a specific contact query: object_type:conversations contact_ids:in:d2e3bde8-4fe4-4a74-9232-5f7458e7a4cb user: find conversations assigned to a specific team query: object_type:conversations team_assignee_id:12345 user: find conversations assigned to a specific admin query: object_type:conversations admin_assignee_id:67890 user: find conversations where Fin participated query: object_type:conversations ai_agent_participated:true Unsupported features: • Complex boolean logic beyond simple AND/OR • Fuzzy matching or proximity searches • Aggregations or analytics queries • Direct conversation content search (use source fields instead) • Real-time or streaming results
fetch
Retrieve detailed content for a specific Intercom resource by ID or URL. Use this tool when you have: - A prefixed ID from search results (e.g., 'conversation_123456', 'contact_abc-def-123', or 'company_abc123') - An Intercom URL (e.g., 'https://app.intercom.com/a/inbox/_/inbox/conversation/123456') Returns: - Full resource content with formatted text summary - Metadata including state, timestamps, and associations - Direct URL to view the resource in Intercom For raw IDs without prefixes, use the specific tools: - 'get_conversation' for conversation IDs - 'get_contact' for contact UUIDs - 'get_company' for company IDs
list_articles
List all articles in the Intercom Help Center. Returns a paginated list of articles with basic metadata. Pagination: - Uses page-based pagination (not cursor-based) - Default: page 1, 25 articles per page - Set 'per_page' (1–150) and 'page' to navigate results - Response includes 'pages' object with total_pages and page count Returns article summaries including id, title, state, and timestamps. Use get_article for full content.
search_articles
Search for articles in the Intercom Help Center. Supports filtering by: - phrase: Free-text search across article title and body - state: Filter by 'published' or 'draft' - help_centre_id: Filter articles by a specific Help Center (numeric ID, uses British spelling to match API) - highlight: When true, returns highlighted matching snippets At least one search parameter must be provided. Returns matching articles with relevance-ranked results. Use get_article for full content.
get_article
Retrieve complete details for a specific Intercom Help Center article. Returns: - Full article content including HTML body - Metadata: title, description, author, state - Timestamps: created_at, updated_at - Parent collection/section information - URL to view the article Use this after list_articles or search_articles to get full article content.
create_article
Create a new article in the Intercom Help Center. Required fields: - title: The article title - author_id: Numeric ID of the admin/teammate who authored the article Optional fields: - description: A short summary of the article - body: The article content in HTML format - state: 'published' or 'draft' (defaults to draft if not specified) - parent_id: Numeric ID of the parent collection or section - parent_type: 'collection' or 'section' (required if parent_id is set) Returns the created article with its new ID and all fields.
update_article
Update an existing article in the Intercom Help Center. Required: - id: The article ID to update Optional fields (only provided fields will be updated): - title: Update the article title - author_id: Change the author (numeric admin/teammate ID) - description: Update the short summary - body: Update the article content (HTML format) - state: Change to 'published' or 'draft' - parent_id: Move to a different collection or section (numeric ID) - parent_type: 'collection' or 'section' (required if parent_id is set) Returns the updated article with all fields.