@grouparoo/intercom

Last Updated: 2021-10-12

Grouparoo's Intercom Plugin enables you to export contacts and tags to Intercom.

This guide will show you how to work with the Intercom Plugin to create a Destination to export your data.

Install the Intercom Plugin

To work with the Intercom Plugin, you must first install it in an existing Grouparoo project. You can do this using grouparoo config and choosing to add the new App. You can also install a plugin with the Grouparoo CLI and use the install command from our CLI: grouparoo install @grouparoo/intercom

Both methods of installation add the package to your package.json file as a dependency, and also drops the Plugin in the grouparoo.plugins section in that same file, which enables it.

// package.json
{
// ...
"dependencies": {
"@grouparoo/intercom": "...",
// ...
},
"grouparoo": {
"plugins": [
"@grouparoo/intercom",
// ...
]
}
}

Once the Plugin is installed, you'll be working primarily with the CLI's configuration commands to get everything set up.

Create a Intercom App

With Grouparoo, an App is how we establish a connection with a Source or Destination. Add this connection by generating an App:

$ grouparoo generate intercom:app my_intercom_app

This will generate a file at config/apps/my_intercom_app.js. Open this file and edit the connection details to match your desired configuration. Here is an example of what this config object will look like after generation:

// config/apps/my_intercom_app.js
exports.default = async function buildConfig() {
return [
{
class: "app",
id: "my_intercom_app",
name: "my_intercom_app",
type: "intercom",
options: {
token: "...",
}
},
];
};

Intercom App Options

Here are the Intercom-specific options available to you in the options section of the config file:

token [required]

Access token from your private App in the developer hub

Validating & Applying Your Config

You can validate your config at any time using the validate command:

$ grouparoo validate

And you can apply that config (save it to your Grouparoo application's database) using the apply command:

$ grouparoo apply

Create an Intercom Destination

Once your App exists, you can generate an Intercom Destination using the generate command. You must specify a parent, which should match the id of the App you just created.

This is the simplest form of Generator for Destinations:

$ grouparoo generate intercom:destination intercom_destination --parent my_intercom_app

This would generate a config file at config/destinations/intercom_destination.js in your Grouparoo project. You can then edit this file to match your desired configuration. Here is an example of what this config object will look like after generation:

// config/destinations/intercom_destination.js

exports.default = async function buildConfig() {
  return [
    {
      id: "intercom_destination",
      name: "intercom_destination",
      class: "destination",
      type: "intercom-export",
      appId: "my_intercom_app",
      groupId: "...",
      syncMode: "...",

      options: {
        creationMode: "User",
        removalMode: "Archive",
      },

      mapping: {
        email: "email",
        firstname: "firstName",
        lastname: "lastName",
      },

      destinationGroupMemberships: {
        "High Value Customers": "highValueCustomers",
      },
    },
  ];
};

For more information on what all these properties mean and how to configure them, see Configuring your Destination.

Sync Modes

The Intercom Destination supports all three sync modes:

  • Sync (sync): Add, update, and remove Records as needed.
  • Additive (additive): Add and update Records as needed, but do not remove anybody.
  • Enrich (enrich): Only update Records that already exist in the Destination. Do not add or remove anybody.

You can set the desired Sync Mode through the syncMode Property in the config file:

syncMode: "additive",

Destination Options

Here are the available options for an Intercom Destination:

creationMode

How should Grouparoo create Intercom contacts? Note that this only applies if using a syncMode that can add new contacts.

Options: User, Lead, Lifecycle
removalMode

How should Grouparoo remove Intercom contacts? Note that this only applies if using a syncMode that can remove existing contacts.

Options: Archive, Delete

You can configure these options by setting them inside the options object of the config file:

options: {
  creationMode: "Lifecycle",
  removalMode: "Archive"
},

Property Mappings

These mappings are what tell Grouparoo which Properties you want to sync to the Destination and what they should be called. For this Plugin, Grouparoo Properties map to Intercom People Attributes.

For Intercom, Mapping the email Property is always required. If creationMode is set to User or Lifecycle, email is also a required Mapping.

You can also map to custom attributes that you've defined on Intercom by adding the custom_attributes prefix (e.g. custom_attributes.my_custom_attribute).

Here's an example of how this would look in the config file. Note that the keys refer to Intercom Attribute names and values refer to Grouparoo Property IDs.

mapping: {
  email: "email",
  name: "firstName",
  "custom_attributes.lifetime_value": "ltv",
},

Group Mappings

You can use Group Memberships to automatically add Intercom Tags to your contacts.

Here's an example of how to configure this in the config file. Keys refer to the name of the tag to be shown on Intercom and values refer to the Grouparoo Group ID.

destinationGroupMemberships: {
  "High Value Customers": "highValueCustomers",
},

Intercom Next Steps

Once you have the Plugin installed, App created, and a Source or Destination configured, you are ready to validate, apply, then import or export your data!