Skip to main content

Intercom

Intercom is a customer messaging platform that helps businesses communicate with customers through live chat, email, in-app messages, and automated bots. It combines support, sales, and engagement tools to help teams build better customer relationships. With Intercom, you can manage conversations, track customer data, send targeted messages, provide self-service support with articles, and automate workflows to scale customer interactions.

Authentication Types​

Intercom supports 1 authentication method:

  • OAuth - Secure, app-based authentication with granular permission control
    • Pros: Secure, per-user access tracking, granular scope control, production-ready, supports all Intercom features
    • Cons: Requires creating an Intercom app in Developer Hub, more complex initial setup
    • Best for: Production deployments, team access, compliance requirements, marketplace apps, any scenario requiring secure multi-user access

Setting up OAuth​

To use Intercom with OAuth, you need to create an Intercom app in the Developer Hub and configure OAuth authentication.

1. Access Intercom Developer Hub​

  1. Log in to your Intercom workspace as an admin

  2. Click on the Settings icon (gear icon) in the bottom left

  3. Navigate to Developers → Developer Hub

    info

    If you don't see the Developer Hub option, make sure you have admin permissions in your Intercom workspace.

2. Create a New App​

  1. In the Developer Hub, click New app → Create app

3. Configure Basic Information​

  1. In your app settings, navigate to the Basic Information tab

  2. Note your Client ID - you'll need this later

  3. Click Show next to Client secret and copy it

    warning

    Keep your Client Secret secure! Never share it publicly or commit it to version control. Anyone with your client secret can access your Intercom data.

4. Configure OAuth & Access Scopes​

  1. Navigate to the Authentication tab in your app settings

  2. Click on Edit

  3. Check the Use OAuth

  4. Under Redirect URLs, click Add redirect URL

  5. Copy the redirect URL from Webrix and paste it exactly as provided

    caution

    The redirect URL must match exactly, including https:// and any trailing slashes. Mismatches will cause authentication failures.

  6. Under OAuth scopes, select the permissions your integration needs:

    Commonly needed scopes:

    • ✅ Read and list users and companies
    • ✅ Write users and companies
    • ✅ Read conversations
    • ✅ Write conversations
    • ✅ Read tickets
    • ✅ Write tickets
    • ✅ Read tags
    • ✅ Read admins
    tip

    Only select the scopes you actually need. Over-requesting permissions can:

    • Make users hesitant to install your integration
    • Cause app review delays if submitting to the Intercom App Store
    • Create unnecessary security risks

  7. Click Save to save your OAuth configuration

5. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Intercom and click Use

  3. Under Authentication Type, select OAuth

  4. Enter your Client ID (from step 3)

  5. Enter your Client Secret (from step 3)

  6. Review the Scopes list and ensure it matches what you configured in Intercom

  7. Click Save Changes

6. Test the Connection​

  1. After saving, click Connect to initiate the OAuth flow

  2. You'll be redirected to Intercom to authorize the app

  3. Review the permissions requested and click Authorize access

  4. You'll be redirected back to Webrix with a successful connection

  5. The connection status should show as Connected

Troubleshooting​

Redirect URI Mismatch Error​

Error: "redirect_uri_mismatch" or "The redirect_uri MUST match the registered callback URL for this application."

Cause: The redirect URL in your Intercom app doesn't match the one being used during OAuth.

Solution:

  1. Copy the exact Redirect URI from Webrix (including https:// and any path)
  2. Go to your Intercom app in Developer Hub → Authentication → Redirect URLs
  3. Remove any existing redirect URLs
  4. Add the exact URL from Webrix
  5. Save the changes and try connecting again
  6. Clear your browser cache if the issue persists

Invalid Client ID or Client Secret​

Error: "invalid_client" or authentication fails immediately.

Cause: The Client ID or Client Secret is incorrect, has extra spaces, or the secret was regenerated.

Solution:

  1. Go to your Intercom app in Developer Hub → Basic Information
  2. Verify the Client ID matches exactly (no extra spaces)
  3. Click Show next to Client secret to reveal it
  4. Copy it carefully and update in Webrix
  5. If you recently regenerated the secret, all existing connections will break and need to be reconnected
  6. Try connecting again

Insufficient Permissions / Access Denied​

Error: 403 Forbidden, "access_denied", or specific API calls fail with permission errors.

Cause: Required OAuth scopes are missing or the admin doesn't have necessary permissions.

Solution:

  1. Check which API operations are failing
  2. Go to your Intercom app → Authentication → OAuth scopes
  3. Add the required scopes (see scope requirements in tool descriptions)
  4. Save the changes
  5. Disconnect and reconnect in Webrix to get new permissions
  6. Ensure the connecting admin has appropriate permissions in Intercom

Common scope requirements:

  • Contact/company operations: "Read and list users and companies", "Write users and companies"
  • Conversation operations: "Read conversations", "Write conversations"
  • Ticket operations: "Read tickets", "Write tickets"
  • Tag operations: "Read tags", "Write tags"

Token Expired or Invalid​

Error: "Unauthorized", "invalid_token", or 401 errors.

Cause: Access token has expired or been revoked.

Solution:

  1. Intercom OAuth tokens typically last 90 days but can be revoked
  2. Disconnect the integration in Webrix
  3. Reconnect to get a fresh token
  4. If the issue persists, check if the app was uninstalled or disabled in Intercom
  5. Verify the app is still active in Developer Hub

Rate Limiting​

Error: 429 Too Many Requests, "rate_limit_exceeded".

Cause: Exceeded Intercom's API rate limits.

Solution:

  1. Intercom's rate limits:
    • 500 requests per minute per workspace (default)
    • Rate limits may vary based on your plan
  2. Implement retry logic with exponential backoff
  3. For bulk operations:
    • Use batch endpoints where available
    • Add delays between requests
    • Process in smaller batches
  4. Consider spreading operations over time rather than making many simultaneous requests
  5. Contact Intercom support if you need higher rate limits for your use case

API Version Header Missing​

Error: Unexpected API responses or version-related errors.

Cause: The Intercom API requires version headers for consistency.

Solution:

The connector automatically includes the Intercom-Version: 2.15 header. If you're seeing version errors:

  1. Ensure you're using the latest version of the Webrix connector
  2. Check that custom configurations haven't removed the header
  3. Verify API calls in logs include the Intercom-Version header

Conversation or Ticket Not Found​

Error: 404 Not Found when accessing conversations or tickets.

Cause: The resource doesn't exist, was deleted, or you don't have access.

Solution:

  1. Verify the ID is correct (Intercom IDs are numeric strings)
  2. Check if the resource was archived or deleted
  3. Ensure the connected admin has access to the conversation/ticket
  4. For conversations: Check if it's in a different workspace
  5. For tickets: Verify the ticket type still exists

Creating Contacts Fails​

Error: 400 Bad Request when creating contacts.

Cause: Missing required fields or invalid data format.

Solution:

  1. Provide either email or external_id when creating contacts
  2. If specifying role, use exactly "user" or "lead"
  3. Ensure email addresses are valid format
  4. Phone numbers should be in E.164 format (e.g., +1234567890)
  5. Custom attributes must match types defined in Intercom data settings

Search Queries Return Unexpected Results​

Cause: Incorrect query format or operator usage.

Solution:

Search queries require specific format:

{
  "query": {
    "field": "field_name",
    "operator": "=",
    "value": "search_value"
  }
}

Valid operators:

  • = - Equals
  • != - Not equals
  • IN - In array
  • NIN - Not in array
  • > - Greater than
  • < - Less than
  • ~ - Contains (text search)
  • ^ - Starts with
  • $ - Ends with

Examples:

// Find open conversations
{"field": "state", "operator": "=", "value": "open"}

// Find contacts with specific email domain
{"field": "email", "operator": "~", "value": "@example.com"}

// Find high priority conversations
{"field": "priority", "operator": "=", "value": "priority"}

Regional API Endpoints​

Issue: Need to use EU or Australian data centers.

Solution:

Intercom has three regional endpoints:

  • US: api.intercom.io (default)
  • EU: api.eu.intercom.io
  • Australia: api.au.intercom.io

The connector automatically routes to your workspace's region. No configuration needed.

Custom Attributes Not Appearing​

Issue: Custom attributes don't show in responses or can't be set.

Solution:

  1. Custom attributes must be defined in Intercom first:
    • Go to Settings → Data → People/Company/Conversation data
    • Create the custom attribute with the correct data type
  2. Use exact attribute names (case-sensitive)
  3. Ensure values match the defined data type (string, number, boolean, date)
  4. List-type attributes must use values from the predefined list

App Review Required​

Issue: Need to publish app to Intercom App Store or seeking wider distribution.

Solution:

If you're building a public integration:

  1. Complete app in Developer Hub with all details
  2. Minimize requested OAuth scopes to only what's needed
  3. Add app icon, screenshots, and clear description
  4. Submit for review in Developer Hub
  5. Review process typically takes 3-5 business days
  6. Address any feedback from Intercom review team

For private apps (internal use only), no review is needed.

Best Practices​

Security​

  • Never share your Client Secret publicly
  • Rotate secrets periodically for security
  • Use minimum scopes required for your use case
  • Monitor API usage for unusual patterns

Performance​

  • Implement pagination for list operations to avoid large responses
  • Use search instead of listing all + filtering locally
  • Cache frequently accessed data like tags and admin lists
  • Batch operations when possible to reduce API calls

Data Management​

  • Use external_id to link contacts with your system's user IDs
  • Archive inactive contacts to manage workspace limits
  • Tag strategically for better organization and filtering
  • Add notes to preserve context and team knowledge

Conversation Management​

  • Close resolved conversations to keep inbox clean
  • Use assignments to route conversations to right team members
  • Add tags to categorize conversations for reporting
  • Reply promptly - Intercom tracks response times

Common Use Cases​

Customer Support Automation​

Use Intercom tools to:

  • Auto-create tickets from certain conversation types
  • Route conversations based on keywords or customer attributes
  • Add notes with AI-generated summaries of conversations
  • Tag conversations automatically based on content

Customer Data Enrichment​

  • Create/update contacts when users sign up in your app
  • Sync customer data between your system and Intercom
  • Add custom attributes based on user behavior
  • Link contacts to companies for B2B workflows

Proactive Messaging​

  • Send targeted messages to user segments
  • Send onboarding messages to new users
  • Announce features to specific customer tiers
  • Re-engage inactive users

Reporting and Analytics​

  • Export conversation data for analysis
  • Track ticket volumes and response times
  • Identify common support topics via tags
  • Monitor customer health via interaction patterns

API Limits and Quotas​

  • Rate Limit: 500 requests per minute per workspace
  • Pagination: Maximum 150 items per page
  • Token Expiry: OAuth tokens valid for approximately 90 days
  • Contact Limit: Varies by Intercom plan
  • Custom Attributes: Varies by plan (typically 100-120 per object)

Additional Resources​

Support​

For issues with:

  • Webrix connector: Contact Webrix support
  • Intercom API: Contact Intercom support or check Intercom Developer Community
  • App review: Contact Intercom via Developer Hub