Intercom Conversation Retriever

This Apify Actor integrates with Intercom API to retrieve conversations based on any contact field criteria.

Features

• Searches contacts by any field (default fields like id, name or custom attributes)
• Finds closed conversations for those contacts after a specified date
• Retrieves full conversation details including message content
• Handles pagination automatically for all API endpoints
• Implements rate limiting and retry logic
• Transforms data into a clean, structured format
• Identifies internal team members vs customers using configurable company settings

Input

Field	Type	Description	Required
apiToken	String	Your Intercom Access Token	Yes
fieldName	String	Attribute to search by (e.g., id, name, custom_attributes.primary_product)	Yes
fieldValues	Array	Array of values to search for in the specified attribute	Yes
dateFrom	String	ISO 8601 date or Unix timestamp for conversation reply filter	Yes
companyEmailDomain	String	Your company's email domain (e.g., 'yourcompany.com')	Yes
companyName	String	Your company name for sender identification	Yes

Field Name Examples

• Default fields: id, name, email, phone
• Custom attributes: custom_attributes.primary_product, custom_attributes.company_id, custom_attributes.user_tier

Output Dataset Structure

{
    "conversation_id": "123456",
    "created_at": "2024-01-15T10:30:00",
    "external_id": "user_789",
    "conversation_parts": [
        {
            "body": "Hello, I need help with my billing issue.",
            "sender": "customer"
        },
        {
            "body": "I'd be happy to help you with that. Can you provide more details?",
            "sender": "Apify"
        }
    ]
}

How It Works

1. Contact Search: Searches for contacts with matching primary_actor_id custom attributes
2. Conversation Discovery: Finds all closed conversations for those contacts created after the specified date
3. Detail Retrieval: Fetches full conversation details including all message parts
4. Data Transformation: Cleans and structures the data for easy consumption

Rate Limiting

The Actor implements conservative rate limiting to respect Intercom's API limits:

• Maximum 150 requests per minute
• Automatic retry with exponential backoff
• Timeout handling with fallback strategies

Error Handling

• Comprehensive logging for debugging
• Graceful handling of API timeouts and rate limits
• Detailed progress reporting throughout the process