Overview
Use this guide to connect your Intercom workspace to Heap Conversation Intelligence through OAuth 2.0.
Conversation Intelligence reads selected Intercom data to ingest and analyze customer conversations. The integration uses read-only permissions and doesn't create, edit, send, or delete anything in your Intercom workspace.
Conversation Intelligence uses the Loris CQA app from the Intercom App Store. You don't need to create an Intercom app or OAuth client, configure users or roles, or set up field-level permissions.
How the connection works
Add the csq_eligible tag to every conversation you want to analyze. Without this tag, no data comes through, even if the connection succeeds. See the CSQ eligible tag guide for detailed instructions.
-
Tag your conversations. Before connecting, apply the
csq_eligibletag in Intercom to every conversation you want Conversation Intelligence to analyze. - Select Intercom in the onboarding wizard. In the Conversation Intelligence setup wizard, select Intercom as the platform you want to connect. To access the setup wizard, see Getting Started with Conversational Intelligence.
- Authorize the connection. Conversation Intelligence redirects you to Intercom's authorization screen, which lists the read-only permissions it requests. Sign in as an Intercom admin and click Authorize. Intercom then redirects you back to Conversation Intelligence.
- Complete the connection. Conversation Intelligence exchanges the authorization for an access token and begins ingesting your tagged conversations.
The initial import of historical conversations runs in the background. The time required depends on the number of conversations in your workspace.
Required permissions
During authorization, Intercom asks you to approve the following read-only permissions. All of them are required for full functionality across chat and email conversations.
| Permission | Why Conversation Intelligence needs it |
|---|---|
| Read conversations | Reads chat and email conversations and their messages. |
| Read admins | Identifies the agents, or admins in Intercom terminology, and teams that handled each conversation for agent-level analytics. |
| Read and list users and companies | Reads the contact and company associated with each conversation for context and segmentation. |
| Read tags |
Reads conversation tags and limits ingestion to conversations
tagged csq_eligible.
|
| Read tickets | Reads back-office tickets, which Intercom calls side conversations, linked to a conversation. |
Intercom may require some permissions by default, including Read and list users and companies, Read conversations, and Read admins. These permissions are read-only.
What Conversation Intelligence reads
Conversation Intelligence uses Intercom's Conversations API for both email and chat conversations.
A conversation is treated as email when its Intercom source.type is email. Other conversations are treated as chat, including Messenger and other non-email channels.
Email conversations
- Subject and opening message
- Subsequent agent and customer replies
- Message timestamps
- Participating agents and contacts
Chat conversations
- Messages
- Message timestamps
- Participating agents and contacts
Data used for both channels
- Conversation tags
- Linked back-office tickets, or side conversations
- Associated contact and company
- Agents and teams involved in the conversation
You don't need to configure individual fields or objects. The permissions described above cover the data required for ingestion and analysis.
Data privacy and disconnecting
- Conversation Intelligence ingests only conversations tagged
csq_eligible. Untagged conversations aren't read. - All access is read-only. Conversation Intelligence can't change your Intercom data.
- Conversation Intelligence uses the authorized access token to retrieve the data required for ingestion and analysis.
- Uninstall the Conversation Intelligence app from your Intercom workspace to disconnect the integration. Conversation Intelligence is notified automatically and stops ingesting data.
Need help?
If you have questions about the required permissions, tagging conversations, or connecting Intercom, contact your Heap Customer Success Manager.