Intercom Integration

Connect Intercom to TR-AI using a Private App token and webhook topics.

Note:TR-AI uses an Intercom Access Token (not OAuth). Replies are posted as the token owner's admin account — type: 'admin' with the resolved admin_id. The type: 'bot' approach requires a dedicated bot token and is not supported.

Credentials required

Field	Where to find it
Access Token	Intercom → Settings → Integrations → Developer Hub → Your App → Authentication → Access Token

Step 1 — Enter credentials in TR-AI

In your TR-AI Dashboard, open the Intercom card. Paste your Access Token and click Save. TR-AI verifies by calling GET https://api.intercom.io/me.

Step 2 — Configure the Intercom webhook

1
Open Webhook settings
Go to Intercom → Settings → Integrations → Developer Hub → Your App → Webhooks.
2
Set the endpoint URL
Webhook endpoint
```
https://ticketresolve.ai/api/integrations/intercom/webhook
```
Intercom routes to the correct trial account using the app_id field in every webhook payload. No :trialId suffix is needed.
3
Subscribe to topics
Enable these two webhook topics:
- conversation.user.created — new inbound conversation.
- conversation.user.replied — customer follow-up reply.

How TR-AI routes Intercom webhooks

Every Intercom webhook payload includes an app_id field. TR-AI resolves the correct trial account by calling GET /me on each active Intercom trial's token and caching the app_id → trialId mapping in memory. Subsequent events for the same workspace are resolved instantly from cache.

Warning:The app_id cache is in-process memory and is lost on server restart. TR-AI re-discovers the mapping automatically on the next webhook event. There is no persistent storage for app_id yet — this is a known limitation.

Bot-loop guard

When TR-AI posts a reply (type: 'admin'), Intercom fires conversation_part.created again. TR-AI guards against this loop by checking the triggering part's author.type:

If author.type is admin or bot → skip processing.
If the triggering part body is empty (state-change event like open/close) → skip.

Follow-up reply handling

For conversation.user.replied events, TR-AI uses the triggering part body as the query — not the original conversation source. This ensures the engine answers the customer's actual new question.

The triggering part is found in data.part (Intercom API v2.10) or as the last element of conversation_parts.conversation_parts.

Reply and close behaviour

After posting a reply, TR-AI closes the conversation (sets state to snoozed for 1 second, effectively closing it). When the customer replies again, Intercom reopens the conversation and fires the webhook again — TR-AI responds to the new message automatically.

Triage behaviour

When TR-AI cannot auto-resolve a conversation, it:

Posts a public acknowledgement reply to the customer.
Re-opens the conversation (since postIntercomReply closes it after sending).
Assigns the conversation to a team named Triage if one exists — otherwise adds a triage tag.
Sends a Slack notification if configured.

Supported webhook topics

Topic	Handled as
conversation.user.created	New conversation
conversation.created	New conversation (legacy alias)
conversation.user.replied	Follow-up reply
conversation_part.created	Follow-up reply (legacy alias)

API version

TR-AI sends Intercom-Version: 2.10 on all API calls.

PreviousJira Service Management NextSalesforce