most relevant results

developer center results

Connect Salesforce to Conversation Intelligence

This feature is only available to paid customers as an add-on. To upgrade, contact your Customer Success Manager or sales@heap.io

Overview

Use this guide to connect your Salesforce environment to Heap Conversation Intelligence through OAuth 2.0.

Conversation Intelligence uses this connection to read select Salesforce records and fields for conversation ingestion and analysis.

The integration supports the following Salesforce channels:

Channel Salesforce data used
Email Case and EmailMessage
Messaging MessagingSession, Conversation, ConversationEntry, ConversationParticipant, and MessagingChannel

Conversation Intelligence requests read-only access. It doesn't create, edit, or delete Salesforce records.

Connect Salesforce

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.

  1. Open the Conversation Intelligence onboarding wizard. To learn how to access the onboarding wizard, see Getting started: Conversational Intelligence. 
  2. Select Salesforce.
  3. Enter your Salesforce production URL.
  4. Add the csq_eligible setting to the conversations you want to ingest.
  5. Select the checkbox confirming I've added the Heap tag and I'm ready to connect.
  6. Click Connect platform.
  7. Sign in to Salesforce and complete the OAuth 2.0 authorization flow.

After authentication is complete and the required permissions are available, Conversation Intelligence can access the approved Salesforce data required for ingestion and analysis.

Salesforce ingestion scope and eligibility

Email, Case and EmailMessage

Conversation Intelligence reads email conversations from Salesforce Case and EmailMessage records.

Terminal-state filter

Email ingestion doesn't apply a hardcoded Closed filter. When the csq_eligible filter is enabled, Conversation Intelligence uses the Salesforce field condition CSQ_Eligible__c = TRUE.

Excluded email records

Draft emails: EmailMessage records with Status = '5' are excluded from the retrieved conversation thread.

Messaging, MessagingSession

Conversation Intelligence reads messaging conversations from Salesforce MessagingSession records and their related conversation records.

Session requirements

A messaging session must meet all of the following conditions:

  • Status = 'Ended'
  • CaseId is not empty
  • MessagingChannel.MessageType = 'EmbeddedMessaging'

Active, waiting, or error sessions aren't ingested. Sessions without an associated Case aren't ingested.

Deleted sessions (IsDeleted = TRUE) aren't ingested.

Conversation Intelligence supports Salesforce Embedded Messaging, also known as Messaging for In-App and Web. Other Salesforce Messaging channel types aren't supported.

Excluded messaging channels

  • WhatsApp
  • Facebook Messenger
  • Apple Business Chat
  • SMS or Text
  • Phone
  • Voice
  • Custom channel types

Eligibility filter

When the csq_eligible filter is enabled, Conversation Intelligence adds the Salesforce condition CSQ_Eligible__c = TRUE.

Unsupported Salesforce channels

Conversation Intelligence doesn't support the following Salesforce channels:

  • SMS through Salesforce Digital Engagement
  • WhatsApp through Salesforce Messaging
  • Facebook Messenger through Salesforce Messaging
  • Apple Business Chat
  • Voice through Salesforce Service Cloud Voice

Conversation Intelligence supports Salesforce Email through Case and Salesforce Messaging through Embedded Messaging only.

Salesforce access requirements

We recommend creating a dedicated Salesforce integration user for Conversation Intelligence. A dedicated user makes access easier to control, audit, and maintain.

The integration user should have Read access to the required objects. View All is optional, but may be needed to ensure the integration user can access all records that should be ingested.

Required object access

Area Objects
Common objects Case, CaseHistory, CaseHistory2 if applicable, CaseComment, Task, and RecordType
Email channel EmailMessage
Messaging channel MessagingSession, Conversation, ConversationEntry, ConversationParticipant, and MessagingChannel
User and agent data User

Required field access

The integration user must have read access to the fields below. If an optional custom field doesn't exist in your Salesforce organization, it can be ignored.

Case

  • Id, Case ID
  • CaseNumber, Case number
  • Subject, subject
  • Description, description
  • Status, status
  • CreatedDate, creation date
  • CreatedById, user who created the Case
  • LastModifiedDate, last modified date
  • LastModifiedById, user who last modified the Case
  • OwnerId, Case owner
  • RecordTypeId, record type ID

Optional custom fields for filtering

Conversation Intelligence can use customer-specific fields to filter which Cases are ingested. Examples include fields for owner, reason, role, brand, or region.

  • Case_Owner_For_Lightning__c, owner-based filtering
  • Case_reason__c, spam or reason filtering
  • Owner_Role__c, role-based filtering
  • NorthAmerica_Brand__c, brand-specific filtering

CaseHistory

  • Id, history record ID
  • CaseId, related Case ID
  • Field, field that changed
  • OldValue, previous value
  • NewValue, new value
  • CreatedDate, change timestamp
  • CreatedById, user who made the change

CaseHistory2

  • Id, history record ID
  • CaseId, related Case ID
  • Status, status value
  • LastModifiedDate, last modified date
  • LastModifiedById, user who made the change

CaseComment

  • Id, comment ID
  • ParentId, related Case ID
  • CommentBody, comment text
  • CreatedDate, creation date
  • CreatedById, user who created the comment

Task

  • Id, Task ID
  • WhatId, related Case ID
  • CallDisposition, wrap-up or disposition, if used

RecordType

  • Id, record type ID
  • Name, record type name
  • Description, record type description

Email fields

EmailMessage

  • Id, email message ID
  • ParentId, related Case ID
  • Subject, email subject
  • TextBody, email body text
  • MessageDate, message timestamp
  • CreatedDate, creation date
  • LastModifiedById, user who last modified the message
  • Incoming, message direction
  • FromAddress, sender email address
  • ToAddress, recipient email address
  • FromName, sender name
  • Status, email status

Messaging fields

MessagingSession

  • Id, messaging session ID
  • CaseId, related Case ID
  • ConversationId, related Conversation ID
  • Status, session status
  • StartTime, session start time
  • EndTime, session end time
  • CreatedDate, creation date
  • CreatedById, user who created the session
  • LastModifiedDate, last modified date
  • MessagingChannelId, messaging channel ID
  • MessagingEndUserId, end-user ID
  • OwnerId, session owner ID
  • AcceptTime, time the session was accepted
  • EndUserMessageCount, number of end-user messages
  • AgentMessageCount, number of agent messages

Conversation

  • Id, Conversation ID
  • ConversationIdentifier, identifier used for mapping

ConversationEntry

  • Id, entry ID
  • ConversationId, related Conversation ID
  • MessageIdentifier, message identifier
  • EntryTime, entry timestamp
  • EntryTimeMilliSecs, milliseconds portion of the timestamp
  • ActorId, actor or participant ID
  • ActorType, agent, end user, system, or bot
  • EntryType, entry type
  • Message, message text when stored in Salesforce
  • Seq, sequence number

ConversationParticipant

  • Id, participant ID
  • ParticipantEntityId, related entity ID
  • JoinedTime, time the participant joined
  • LeftTime, time the participant left

MessagingChannel

  • Id, channel ID
  • MessageType, channel type

Need help?

If you have questions about the required Salesforce permissions, OAuth setup, supported channels, or the csq_eligible configuration, contact your Heap Customer Success Manager.

Last updated
Powered by Zendesk