Tags in Intercom

As an Intercom user, you can classify your contacts, companies, and conversations by applying tags. A tag is a word or a combination of words that can be used to gather meaningful information, build reports, or provide better support to your customers. For example, you can tag customers who have subscribed to your premium support plan as “Premium Customers”, and generate a report based on that tag.

You can create an Activation to apply or remove tags to and from the data that you fetch from the Warehouse. Hevo matches the data in the Warehouse with that in the Target using the selected unique identifier and then applies or removes tags to/from the matched Target object records. You can only apply or remove tags for the contact, company, and conversation Intercom objects types. To achieve this, Hevo creates the contact_tag, the company_tag, and the conversation_tag objects, respectively. The prefix helps to distinguish the object type on which the tag must be applied or removed.

---

Prerequisites

• The Can manage tags permission is enabled for the connecting Intercom user.

---

Scopes

Apart from the default scopes that Activate needs for Intercom, it needs the following scopes to support tags:

Scope	Description	Resources
Read tags	Allows Hevo to list all created tags.	Tags
Write tags	Allows Hevo to create, update, use, and delete tags.	Tags
Write conversations	Allows Hevo to update and respond to conversations.	Conversations
Read admins	Allows Hevo to attach to and detach tags from conversations.	Admins

---

Field Mapping in Intercom Tags

Once you have configured an Intercom Target, you can use that in an Activation to attach or detach tags. The Activation SQL query helps you identify the Intercom object records on which the tags are to be applied or removed. You can only attach or detach tags for the contact, company, and conversation object types; for this, you must use the <object-name>_tag objects that Hevo created.

To complete creating the Activation, you must map the query fields in the Field Mapping page.

To do this:

1. In the Field Mapping page, specify the following:

   

   • Select the Target Object: Select one of the Hevo created objects, contact_tag, company_tag, or conversation_tag. Once you do this, the sync behaviors get enabled for selection. If you had selected a Target object in the Select the Data to be Synchronized step, the same object is displayed here. You can change this value.

   • Select the Sync Behavior: Select one of the following options:

     • Attach Tag to Records: Select an existing tag from the drop-down list or create a tag and attach it to the Target object records.

     • Detach Tag(s) from Records: Select one or more tags from the drop-down list to detach from the Target object records.

     Note: All existing tags available in Intercom to the connected user are displayed in the drop-down list.

   • Match the query field with the Target field…: Select a query field to match with the Target field. All unselected fields are dropped.

     • Query Field: Select a compatible query field from the drop-down to match with the Target field.

     • Target Field: Select the Target field that you want to match with the query field. The available Target fields are the unique identifier(s) for the selected Target object. For the contact_tag and conversation_tag objects, this is id, while for the company_tag object, it is id or company_id. This field is automatically selected if the Target object has only one unique identifier.

     Note: Tags are applied to or removed from records only where the query field matches the Target field.

2. Specify a unique Activation Name.

3. Click CREATE ACTIVATION.

Modifying an Activation in Intercom Tags

In an Activation created to attach or detach tags, you can only modify the Activation SQL query. This is because the unique identifiers are mapped while creating the Activation, and you cannot modify the unique identifier of a created Activation. Read Limitations of Data Synchronization Identifiers.

You can modify the SQL query in the SQL QUERY dialog and validate and save it. The saved query is used immediately by the Activation.

---

Data Replication

Activate supports the following synchronization behaviors for the tag objects that it created:

• Attach Tag to Records (Attach)

• Detach Tag(s) from Records (Detach)

To attach a tag to or detach tag(s) from the company object type, Batch API endpoints are used. These API endpoints allow attaching or detaching tags on up to 100 companies in a single call. If any of the companies in the list sent to the API do not exist, the synchronization is failed. In the case of the contact and conversation object types, the modifications are made one by one and not in batches. Read Synchronization Behaviors.

Activate attaches or detaches tag(s) using these unique identifiers:

Unique Identifiers	Description
id	The unique value that Intercom automatically assigned to an object record when it was created.
company_id	The value of the company_id field as defined by you for the company object records.

You can use the unique identifiers to attach a tag to or detach tag(s) from any of the object types, contact, company, and conversation by selecting the corresponding tag object that Hevo created. Refer to section, Data Model for the mapping of the tag objects and their identifier(s).

In Attach, a tag is attached and in Detach, tag(s) are detached from the Target object records. The records are identified by the Activation SQL query, and if the specified unique identifier does not match any Target object records, the synchronization is failed.

In Attach, you can attach an existing tag or create one. In Detach, you can detach single or multiple tags. Of the specified tags, only those tags found on the Target object records are detached. Also, if any of the specified tags cannot be detached from some of the Target object records, then those records are marked as FAILED.

For example, suppose you want to detach the tags, “Paid Customer” and “Region-EU” from the conversation object type. To achieve this:

1. Write an SQL query to identify all the conversations having the tags that you want to detach.

2. Select the conversation_tag object.

3. Select the tags, “Paid Customer” and “Region-EU” from the drop-down list.

4. Match the id field from the query with the id field of the conversation_tag object.

Suppose, the query identifies conversations with id values 100, 101, and 102 as having the tags you want to detach. Then, the Activation flow is as follows:

---

Data Model

The following table lists the objects created in Hevo and the unique identifiers used by Activate to synchronize the tags:

Object	Unique Identifier(s)	Description
contact_tag	- id	An object created in Hevo to assign tags to the contacts in Intercom based on the value of the id field.
company_tag	- id - external_id	An object created in Hevo to assign tags to the companies in Intercom based on the values of the id or company_id field.
conversation_tag	- id	An object created in Hevo to assign tags to the conversations in Intercom based on the value of the id field.

Note: The unique identifiers of each of these objects are the only Target fields available for selection while mapping the query fields to the Target object fields.

---

Revision History