Intercom via Segment CDP: 10 low-level tips for smooth integration

Posted on November 21, 2024 by Datomni Client Successin Segment CDP

When building your customer data infrastructure—even if you’re opting for the simplest approach by using a ready-to-go SaaS customer data platform—you need to decide how to activate your data, specifically which end-destinations to connect to your customer data flows.

CDP vendors often claim you can seamlessly connect everything to everything, but that’s not entirely true. Some destinations require a bit more foresight and planning than others.

We recently completed a Segment CDP implementation for a client in Asia with a stack that included Intercom in the activation layer, running as a Segment destination. During the process, we encountered several implementation quirks that inspired the following guide. This article wraps up our findings and provides actionable insights for implementing Segment with Intercom effectively. Let’s dive in!

Why Segment-Intercom integration matters

Segment is a SaaS-based customer data platform (CDP) that helps you collect, transform, and send customer data to various tools, including Intercom. Intercom makes it easy to build user communication and engagement flows. Intercom is one of many destinations available in Segment.

A well-implemented integration ensures:

  • Accurate user data synchronization.
  • Reliable event tracking, validated in real time with Segment event protocols.
  • Improved personalization and customer insights.

Common issues in the Segment implementation

The following key issues are common in Segment-Intercom integrations:

  • track events not appearing in Intercom
  • Missing users in Intercom
  • Data sync delays
  • Incorrect or incomplete traits objects

Segment-Intercom integration: implementation tips

Remove native Intercom library

Before integrating Segment, ensure that any native Intercom library previously implemented is removed. All data must flow exclusively through Segment to avoid conflicts or duplicate data issues.

Use Segment’s identify method correctly

The identify method, Segment’s tool for user identification, is crucial for creating user records in Intercom and ensuring proper integration between Segment and Intercom. An identify call, containing a userId, must precede any track call, as Intercom associates track events only with known users. This can be challenging for two reasons:

Batching events

Segment’s server-side libraries often group multiple events into a single batch request to reduce network usage and improve performance, especially in high-volume environments. However, this batching can disrupt the intended order of events. For example, an identify call (to associate user data) might be grouped with a track event (to log a user action), potentially causing issues if Segment processes the track event before the identify.

Some events, such as identify, must always be processed before others like track:

  • identify: Attaches user metadata to Segment’s database (e.g., user ID, email).
  • track: Logs user activities, often tied to an identified user.
  • If the identify event hasn’t been processed yet, Segment won’t know which user the track event belongs to.

To enforce this order, you can use Segment’s flush() method. The flush method ensures all queued events are sent to Segment immediately, guaranteeing that an identify event is processed before any subsequent events like track or page.

Retry timing

If the identify call is delayed or retried after the track call, the event may not be recorded in Intercom.

Restrict custom trait length

When doing the Segment CDP implementation, we make use of a useful Segment feature called Custom Traits, which helps us record more custom datapoints at the user level. Ensure that all custom trait values in your calls are shorter than 255 characters. Intercom enforces this limit to optimize data handling and processing.

Include required traits in identify calls

Include the following special traits for every identify call to maximize compatibility with Intercom and get access to the full scope of Intercom features.

  • email: This is automatically added by Segment.
  • firstName and lastName: Helps personalize Intercom communication.
  • createdAt: Timestamp indicating when the user was created.
  • company: Associating users with their company adds context.

Enhance the context object

To provide richer data for Intercom, add the following properties to the context object in Segment:

  • active: true: This ensures the Intercom last_request_at field updates appropriately.
  • userAgent: Captures details about the user’s browser or device.
  • ip: Ensures accurate geolocation and session tracking.

Standardize property names

Align Segment and Intercom property conventions:

  • Change customer_id to user_id for compatibility.
  • Include groupId, along with email or user_id, in all group method calls.

For completeness, property names can also be changed within the Segment interface. However, at Datomni, we believe that anything that can be done in code should be done in code, a sentiment our CEO highlighted in a recent interview for The Martech Summit.

Avoid unsupported data structures

Intercom doesn’t support custom arrays or nested objects. Ensure that all custom properties are sent at the top level in your payloads.

Pass a secure user hash

For secure user identification, include a user_hash in the integrations object. This is a SHA256 hash of your Intercom API secret and the userId.

Example in Ruby:

rubyCopy codeIntercom: {
  user_hash: '<%= OpenSSL::HMAC.hexdigest("sha256", "YOUR_INTERCOM_APP_SECRET", current_user.id) %>'
}

Update “Last Seen” trait

Intercom updates the Last Seen user trait when:

  • A user’s profile is updated via identify calls.
  • A group call is sent containing the userId.

Ensure these calls are properly configured to keep the Last Seen field accurate.

Best practices for a smooth integration

Segment is a highly technical platform. Even with our quick tips, whenever you’re implementing Segment Customer Data Platform (CDP), you should always remember to do the following:

  • Use Segment Debugger: Validate your events in real time using Segment’s Debugger. This helps ensure data consistency and accuracy.
  • Set up error monitoring: Use logging and monitoring tools to identify and fix issues proactively.
  • Collaborate with developers: Work closely with your development team to resolve structural or coding issues.

Conclusion

By following this guide and adhering to best practices, you’ll ensure that your integration is robust, scalable, and tailored to your business needs.

If you need help with your Segment implementation or want to transform Segment into a powerful customer data infrastructure with a smart approach to MTU utilization and a private reporting platform, check out our Segment CDP implementation service and explore one of our case studies, such as implementing Segment for a Y Combinator company.

Additional resources

Photo by fabio on Unsplash.