How to connect Intercom to an AI Agent

Connect your Flametree AI agent to Intercom the seamless customer service suite to process incoming customer messages via the Intercom Inbox widget, and then respond directly to your customers or with suggested draft messages to human operators based on the configured mode.

Prerequisites

💡 Note: If necessary, please refer to How to Find the Required Parameters.

Prior to setting up the Intercom Integration, ensure the following prerequisites are met:

1. An Intercom account with access to the Developer Hub;
2. Select the appropriate Intercom API URL/Server for your region;
   • Available API Servers may be found in the Intercom Developer Docs. Please check under Related Resources.
   • For example: https://api.intercom.io/ (US)
3. An Access Token (I.e. An API key used for authorization), and;
4. An Admin ID, the administrator identifier (Email ID) from which your AI agent is to send messages.

What is Intercom?

Intercom.com is customer service suite that delivers faster response times, personalized service and a consolidated view of customer services through its Fin AI Agent and Helpdesk.

Learn More About Intercom

How to Find the Required Parameters

Access Token

1. In Intercom, Navigate to:

   • Settings → Integrations → Developer Hub → Your App → Authentication → Access Token

2. Click the Reveal 👁️ and/or Copy to clipboard 📋 icons to view and/or save the token.

Admin ID

1. Option A: Intercom Inbox URL

   • Via the Intercom Inbox for your app, inspect the Browser URL to find the Admin ID.
   • For example: https://app.intercom.com/a/inbox/<APP_ID>/inbox/admin/<ADMIN_ID>/conversation/<CONVERSATION_ID> (I.e. <ADMIN_ID>)

2. Option B: API Call

   • Via CMD (Windows Command Prompt) or Powershell, run the following command replacing <YOUR_TOKEN> with the Intercom Access Token retrieved earlier.

curl -i -X GET -H "Authorization: Bearer <YOUR_TOKEN>" -H "Intercom-Version: 2.11" "https://api.intercom.io/me"

Step-by-Step Integration Setup

Step 1: Add/Set up the Intercom Integration in Flametree

1. Navigate to Integrations

   • Go to the Channels section/tab, and;
   • Find Intercom and click Add +

2. Fill Configuration

Field	Description	Required	Where to Get Value
Name	Custom integration name.	✅ Yes	Your choice
Description	Integration description.	✅ Yes	Your choice
Intercom URL	Intercom API URL/Server based on your region, E.g. https://api.intercom.io/.	✅ Yes	Intercom Developer Documentation: Related Resources
API Key	Intercom Access Token used to access workspace data via the API.	✅ Yes	Intercom Developer Hub
Admin ID	Admin ID (Email ID) from which an agent should send messages.	✅ Yes	Intercom Inbox URL or API call
Integration Type (Mode)	Determines how an agent replies to customers and/or human operators. Please refer to Supported Integration Types for more detail.	✅ Yes	Enter one of the following: copilot, copilot_private or hybrid

Supported Integration Types

Integration Type / Mode	Description
copilot	If set to copilot, an agent will reply directly to customers.
copilot_private	Alternatively, if set to copilot_private, an agent will instead reply with suggested draft messages in the conversations of a human operator's Intercom Inbox.
hybrid	If set to hybrid, an agent is capable of replying both directly to customers and with suggested draft messages to human operators. The manner in which an agent will reply is dependent on it's Copilot Working Hours.

3. Save Integration
   • Click Save to create the integration

Step 2: Connect to AI Agent

1. Open Agent Configuration

   • Navigate to your target AI agent's settings, and;
   • Go to the Channels section.

2. Assign Integration

   • Select your Intercom Integration from the list, and;
   • Save the agent configuration.

3. Restart Agent

   • Restart the agent for changes to take effect.
   • This step is mandatory for the integration to work.

❗️ Important: Always restart both the agent and channel after making changes.

Step 3: Configure the Webhook in Intercom

1. Retrieve the Webhook URL from Your Agent
   • Navigate to your target AI agent's settings;
   • Go to the Channels section, find Intercom;
   • Click the Show URLs icon 🔗 and;
   • Click the Copy 📋 icon to save the Webhook URL.

💡 Note: Ensure your AI agent is running in Flametree before updating the Intercom Webhook.

2. Configure the Intercom Webhook
   • In the Intercom, navigate to: Settings → Integrations → Developer Hub → Your App → Webhooks;
   • Click Edit, and;
   • For the Endpoint URL, place the Webhook URL copied from your agent and click Save.

💡 Note: If successful, a pop-up then appears in Intercom with the following message: Your webhook settings were successfully updated and a test request was sent successfully. Please refer to Common Issues & Solutions if this does not occur.

3. Inspect the Agent's Intercom Logs
   • In Flametree, navigate to Agents;
   • Find your agent, click the vertical ellipsis ⋮ and then click Show Logs;
   • Switch to the Intercom tab. Here (If successful) you'll find the test request sent by Intercom after editing the Webhook.
   • For example:

{
    "type": "notification_event",
    "app_id": "<APP_ID>",
    "data": {
        "type": "notification_event_data",
        "item": {
            "type": "ping",
            "message": "This is a ping notification test message."
        }
    },
    "links": {},
    "id": null,
    "topic": "ping",
    "delivery_status": null,
    "delivery_attempts": 1,
    "delivered_at": 0,
    "first_sent_at": "<FIRST_SENT_AT>",
    "created_at": "<CREATED_AT>",
    "self": null
}

Step 4: Additional Configuration

1. Configure the Copilot Working Hours for an Agent
   • Navigate to your target AI agent's settings;
   • Go to the Advanced section;
   • Click + for one of the days of the week;
   • Enter the hours from which Copilot workings hours start and end (E.g. 7 to 24), and;
   • Repeat for the other necessary days of the week.

💡 Note: This step is optional, however please configure Copilot working hours if the Integration Type / Mode is set to hybrid for your Intercom Integration and the agent should reply both directly to customers and with suggested draft messages to human operators during specific periods of the day.

2. Restart Agent
   • Restart the agent for changes to take effect.

❗️ Important: Always restart both the agent and channel after making changes.

Configuration Options

Environment Variables

Configure additional features through Set Environment Variables:

Variable	Description	Default
INTERCOM_TEAM_ID_FILTER	A comma-separated list of Intercom team IDs from which the agent should accept messages. For example: INTERCOM_TEAM_ID_FILTER=7727961,7727960	True

To Configure:

1. Go to your agent's Set Environment Variables and click +;
2. Add the variable name and desired value, and;
3. Save and restart the agent (If it is already running)

Testing Your Integration

Quick Test Steps

1. Send Endpoint Test Request

   • In the Intercom, navigate to: Settings → Integrations → Developer Hub → Your App → Webhooks;
   • Click Send a test request, and;
   • Expected Pop-up Message: Test request sent successfully

2. Send Test Message

   • Use the Intercom Inbox widget to send a message, and;
   • Verify the AI agent responds appropriately.

3. Check Message Delivery

   • Confirm messages appear in the Intercom Inbox, and;
   • Verify that sessions are created in Flametree.

Common Issues & Solutions

Test request sent after editing the Intercom Webhook is unsuccessful

Pop-up Message: Unsuccessful test request. Please check that your Endpoint URL can receive notifications and check for errors.

Possible Causes:

• Invalid Endpoint URL or;
• Flametree AI agent is not running.

Solutions:

1. Verify Flametree Agent: Ensure the agent is running.

Agent does not reply to messages in Intercom

Possible Causes:

• Agent not restarted after integration setup.
• Wrong Admin ID configured.
• Incorrect mode (Mode other than copilot, copilot_private, and hybrid).

Solutions:

1. Double-check: Admin ID, integration mode, and restart the agent.

FAQ

What message types are supported?

Intercom together with Flametree supports:

• ✅ Text messages
• ✅ Images
• ✅ Voice messages
• ❌ Voice calls
• ❌ Video calls

Is configuring Copilot working hours mandatory if the Integration Type is set to hybrid?

Configuring Copilot working hours is not mandatory. If working hours are not configured and the Integration Type is set to hybrid, your agent will reply directly to customers similarly to Integration Type copilot.

Security Considerations

API Token Security

• Never share your access tokens publicly;
• Rotate tokens regularly for enhanced security;
• Use environment variables in production deployments, and;
• Monitor API usage for suspicious activity

Related Resources

• What is Intercom?
• Intercom API
• Intercom Developer Documentation
• Agent Configuration Guide
• Environment Variables