Open Skills Logo
Open Skills

intercom-automation

Automate Intercom tasks via Rube MCP (Composio): conversations, contacts, companies, segments, admins. Always search tools first for current schemas.

View Source
name:intercom-automationdescription:"Automate Intercom tasks via Rube MCP (Composio): conversations, contacts, companies, segments, admins. Always search tools first for current schemas."requires:mcp:[rube]

Intercom Automation via Rube MCP

Automate Intercom operations through Composio's Intercom toolkit via Rube MCP.

Prerequisites

  • Rube MCP must be connected (RUBE_SEARCH_TOOLS available)

  • Active Intercom connection via RUBE_MANAGE_CONNECTIONS with toolkit intercom

  • Always call RUBE_SEARCH_TOOLS first to get current tool schemas

    • Setup

    Get Rube MCP: Add https://rube.app/mcp as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.


  • Verify Rube MCP is available by confirming RUBE_SEARCH_TOOLS responds

  • Call RUBE_MANAGE_CONNECTIONS with toolkit intercom

  • If connection is not ACTIVE, follow the returned auth link to complete Intercom OAuth

  • Confirm connection status shows ACTIVE before running any workflows

    • Core Workflows

    1. Manage Conversations

    When to use: User wants to create, list, search, or manage support conversations

    Tool sequence:

  • INTERCOM_LIST_ALL_ADMINS - Get admin IDs for assignment [Prerequisite]

  • INTERCOM_LIST_CONVERSATIONS - List all conversations [Optional]

  • INTERCOM_SEARCH_CONVERSATIONS - Search with filters [Optional]

  • INTERCOM_GET_CONVERSATION - Get conversation details [Optional]

  • INTERCOM_CREATE_CONVERSATION - Create a new conversation [Optional]

    • Key parameters:

  • from: Object with type ('user'/'lead') and id for conversation creator

  • body: Message body (HTML supported)

  • id: Conversation ID for retrieval

  • query: Search query object with field, operator, value

    • Pitfalls:

  • CREATE_CONVERSATION requires a contact (user/lead) as the from field, not an admin

  • Conversation bodies support HTML; plain text is auto-wrapped in

    tags


  • Search query uses structured filter objects, not free-text search

  • Conversation IDs are numeric strings

    • 2. Reply and Manage Conversation State

    When to use: User wants to reply to, close, reopen, or assign conversations

    Tool sequence:

  • INTERCOM_GET_CONVERSATION - Get current state [Prerequisite]

  • INTERCOM_REPLY_TO_CONVERSATION - Add a reply [Optional]

  • INTERCOM_ASSIGN_CONVERSATION - Assign to admin/team [Optional]

  • INTERCOM_CLOSE_CONVERSATION - Close conversation [Optional]

  • INTERCOM_REOPEN_CONVERSATION - Reopen closed conversation [Optional]

    • Key parameters:

  • conversation_id / id: Conversation ID

  • body: Reply message body (HTML supported)

  • type: Reply type ('admin' or 'user')

  • admin_id: Admin ID for replies from admin, assignment, and close/reopen

  • assignee_id: Admin or team ID for assignment

  • message_type: 'comment' (default) or 'note' (internal)

    • Pitfalls:

  • admin_id is REQUIRED for admin replies, close, reopen, and assignment operations

  • Always fetch admin IDs first with LIST_ALL_ADMINS or IDENTIFY_AN_ADMIN

  • Duplicate sends can occur on retry; implement idempotency checks

  • Internal notes use message_type: 'note'; visible only to workspace members

  • Closing requires an admin_id and optional body message

    • 3. Manage Contacts

    When to use: User wants to search, view, or manage contacts (users and leads)

    Tool sequence:

  • INTERCOM_SEARCH_CONTACTS - Search contacts with filters [Required]

  • INTERCOM_GET_A_CONTACT - Get specific contact [Optional]

  • INTERCOM_SHOW_CONTACT_BY_EXTERNAL_ID - Look up by external ID [Optional]

  • INTERCOM_LIST_CONTACTS - List all contacts [Optional]

  • INTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACT - Get contact tags [Optional]

  • INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT - Get contact segments [Optional]

  • INTERCOM_DETACH_A_CONTACT - Remove contact from company [Optional]

    • Key parameters:

  • contact_id: Contact ID for retrieval

  • external_id: External system ID for lookup

  • query: Search filter object with field, operator, value

  • pagination: Object with per_page and starting_after cursor

    • Pitfalls:

  • SEARCH_CONTACTS uses structured query filters, not free-text; format: {field, operator, value}

  • Supported operators: =, !=, >, <, ~ (contains), !~ (not contains), IN, NIN

  • Contact types are 'user' (identified) or 'lead' (anonymous)

  • LIST_CONTACTS returns paginated results; use starting_after cursor for pagination

  • External IDs are case-sensitive

    • 4. Manage Admins and Teams

    When to use: User wants to list workspace admins or identify specific admins

    Tool sequence:

  • INTERCOM_LIST_ALL_ADMINS - List all admins and teams [Required]

  • INTERCOM_IDENTIFY_AN_ADMIN - Get specific admin details [Optional]

    • Key parameters:

  • admin_id: Admin ID for identification

    • Pitfalls:

  • LIST_ALL_ADMINS returns both admins and teams

  • Admin IDs are required for conversation replies, assignment, close, and reopen

  • Teams appear in the admins list with type: 'team'

    • 5. View Segments and Counts

    When to use: User wants to view segments or get aggregate counts

    Tool sequence:

  • INTERCOM_LIST_SEGMENTS - List all segments [Optional]

  • INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACT - Segments for a contact [Optional]

  • INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES - Segments for a company [Optional]

  • INTERCOM_GET_COUNTS - Get aggregate counts [Optional]

    • Key parameters:

  • contact_id: Contact ID for segment lookup

  • company_id: Company ID for segment lookup

  • type: Count type ('conversation', 'company', 'user', 'tag', 'segment')

  • count: Sub-count type

    • Pitfalls:

  • GET_COUNTS returns approximate counts, not exact numbers

  • Segment membership is computed; changes may not reflect immediately

    • 6. Manage Companies

    When to use: User wants to list companies or manage company-contact relationships

    Tool sequence:

  • INTERCOM_LIST_ALL_COMPANIES - List all companies [Required]

  • INTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIES - Get company segments [Optional]

  • INTERCOM_DETACH_A_CONTACT - Remove contact from company [Optional]

    • Key parameters:

  • company_id: Company ID

  • contact_id: Contact ID for detachment

  • page: Page number for pagination

  • per_page: Results per page

    • Pitfalls:

  • Company-contact relationships are managed through contact endpoints

  • DETACH_A_CONTACT removes the contact-company association, not the contact itself

    • Common Patterns

    Search Query Filters

    Single filter:

    {
      "field": "email",
      "operator": "=",
      "value": "user@example.com"
    }

    Multiple filters (AND):

    {
      "operator": "AND",
      "value": [
        {"field": "role", "operator": "=", "value": "user"},
        {"field": "created_at", "operator": ">", "value": 1672531200}
      ]
    }

    Supported fields for contacts: email, name, role, created_at, updated_at, signed_up_at, last_seen_at, external_id

    Supported fields for conversations: created_at, updated_at, source.type, state, open, read

    Pagination

  • Most list endpoints use cursor-based pagination

  • Check response for pages.next with starting_after cursor

  • Pass cursor in pagination.starting_after for next page

  • Continue until pages.next is null

    • Admin ID Resolution

    1. Call INTERCOM_LIST_ALL_ADMINS to get all admins
  • Find the desired admin by name or email

  • Use admin.id for replies, assignments, and state changes

    • Known Pitfalls

    Admin ID Requirement:

  • Admin ID is required for: reply (as admin), assign, close, reopen

  • Always resolve admin IDs first with LIST_ALL_ADMINS

    • HTML Content:

  • Conversation bodies are HTML

  • Plain text is auto-wrapped in paragraph tags

  • Sanitize HTML input to prevent rendering issues

    • Idempotency:

  • Replies and conversation creation are not idempotent

  • Duplicate sends can occur on retry or timeout

  • Track message IDs to prevent duplicates

    • Rate Limits:

  • Default: ~1000 requests per minute (varies by plan)

  • 429 responses include rate limit headers

  • Implement exponential backoff for retries

    • Quick Reference

    TaskTool SlugKey Params
    List conversationsINTERCOM_LIST_CONVERSATIONS(pagination)
    Search conversationsINTERCOM_SEARCH_CONVERSATIONSquery
    Get conversationINTERCOM_GET_CONVERSATIONid
    Create conversationINTERCOM_CREATE_CONVERSATIONfrom, body
    Reply to conversationINTERCOM_REPLY_TO_CONVERSATIONconversation_id, body, admin_id
    Assign conversationINTERCOM_ASSIGN_CONVERSATIONconversation_id, admin_id, assignee_id
    Close conversationINTERCOM_CLOSE_CONVERSATIONid, admin_id
    Reopen conversationINTERCOM_REOPEN_CONVERSATIONid, admin_id
    Search contactsINTERCOM_SEARCH_CONTACTSquery
    Get contactINTERCOM_GET_A_CONTACTcontact_id
    Contact by external IDINTERCOM_SHOW_CONTACT_BY_EXTERNAL_IDexternal_id
    List contactsINTERCOM_LIST_CONTACTS(pagination)
    Contact tagsINTERCOM_LIST_TAGS_ATTACHED_TO_A_CONTACTcontact_id
    Contact segmentsINTERCOM_LIST_ATTACHED_SEGMENTS_FOR_CONTACTcontact_id
    Detach contactINTERCOM_DETACH_A_CONTACTcontact_id, company_id
    List adminsINTERCOM_LIST_ALL_ADMINS(none)
    Identify adminINTERCOM_IDENTIFY_AN_ADMINadmin_id
    List segmentsINTERCOM_LIST_SEGMENTS(none)
    Company segmentsINTERCOM_LIST_ATTACHED_SEGMENTS_FOR_COMPANIEScompany_id
    Get countsINTERCOM_GET_COUNTStype, count
    List companiesINTERCOM_LIST_ALL_COMPANIESpage, per_page