Using segments and tags

In this part of the series we will work through some simple examples of using segments and tags to group customers. One example of how you might group customers is for offline processing. You might want to build up a group of customers based on their behaviour over a period of a month. Then at then end of the month you want to get the list of these customers and look for patterns or trends for these users. Maybe it is customers who opened X number of conversations in a month or unsubscribed from a service. Either way you want to see if there is some think you can learn from these customers.

Creating you segments

First things first, you will want to setup your segments or tags. As noted you can see how to setup your segment via the UI here. You might want to add users based on the last time they were active or the fact that they triggered an unsubscribe event for example:

Create your tags

You can create your tags via the API. Continuing with the offline example, you may want to tag potential sales leads.These may be tagged manually by your customer service team as they chat to customers and feel that they would benefit from speaking to someone on your sales team:

1000 — Then simply click on the 'Tag' button to either create a new tag or add to an existing one

You can also tag resources via the API, when you use the API to tag a resource you will create a new tag if it does not exist.

🚧
Use ID for leads
If you are tagging leads you will need to use the Intercom ID. For users you can use either the ID, user_id or email.

var Intercom = require('intercom-client');

var client = new Intercom.Client({ token: process.env['AT'] });
var tag = process.argv[2];
var tag_user = process.argv[3];
// Using the ID (value in the URL) you can tag either users or leads. 
// If you use user_id or email you can only tag users
client.tags.tag({name: tag, users: [{ id: tag_user }] }, function (rsp){
  console.log(rsp.body)
});

> node tag_user.js value_lead '4b041896db50f992a0d4df2c'

// You can tag a list of users and leads in one go if you like
client.tags.tag({name: tag, users: [{ user_id: tag_user }, {id: tag_lead}, {email: user_email}] }, function (rsp){
    console.log(rsp.body)
});

Find the customers you just tagged or added to a segment

Now that you know how to add customers to your segments and tags you will want to be able to discover which of you customers are in these new groupings. There are three main actions you will want to perform on tags or segments. You can see these actions outlined in the diagram here:

720 — The actions and associated endpoints for tags and segments

The actions are:

List your tags or segments: This action will list all the tags or segments you have created for your app. In the list returned you will be able to see the ID associated with the relevant tag or segment. This is very important since you need this ID to get the list of resources associated with that record.
List the customers in your tag/segment: To list the customers in your tag or your segment you will need to know the tag or segment ID. Then you can go to the users endpoint and retrieve the users associated with that resource
Get the counts of your tags/segments: You may just want to get a global count of all your tags, segments or companies. You can do this using the counts endpoint

Get the counts of your tag and segments

To look at how many resources are in our tags or segments we can use the count endpoint as follows:

var Intercom = require('intercom-client');

var client = new Intercom.Client({ token: process.env['AT'] });

client.counts.userTagCounts(function (rsp){
    console.log(rsp.body.user)
});

> node count_user_tags

{ tag:
   [ {'multi-id': 3 },
     { tag_test: 1 },
     { tag_test2: 0 },
     { tag1: 0 },
     { tag2: 0 },
     { value_lead: 3 } ] }

// To get segment counts just replace the call with 
//client.counts.userSegmentCounts(callback)
var Intercom = require('intercom-client');
var client = new Intercom.Client({ token: process.env['AT'] });

client.counts.userSegmentCounts(function (rsp){
    console.log(rsp.body.user)
});

Get the customers in your tags and segments

So far we have created segments and tags and from the counts we can see whether these tags and segments have been populated. The next step is to list the customers that are in these tags or segments. As you can see from the diagram above this is a two step process:

First get the ID associated with the tag or segment you are interested in
Next go to the users endpoint and use the ID to list the users associated with that tag or segment

Get the list of tags/segments and then use the ID to get the list of users

var Intercom = require('intercom-client');

var client = new Intercom.Client({ token: process.env['AT'] });
client.tags.list(function (rsp){
    console.log(rsp.body)
});

{ type: 'tag.list',
  tags:
   [ { type: 'tag', id: '1174399', name: 'multi-id' },
     { type: 'tag', id: '730128', name: 'tag_test' },
     { type: 'tag', id: '1028594', name: 'tag_test2' },
     { type: 'tag', id: '1201455', name: 'tag1' },
     { type: 'tag', id: '1201457', name: 'tag2' },
     { type: 'tag', id: '1373897', name: 'value_lead' } ] }

var Intercom = require('intercom-client');

var client = new Intercom.Client({ token: process.env['AT'] });
var tag_id = process.argv[2];
client.users.listBy({tag_id: tag_id}, function (rsp){
    console.log(rsp.body)
});

> node list_users.js '1373897'

# Returns a list containing all the customers (leads and/or users) in the tag
{ type: 'user.list',
  pages:
   { type: 'pages',
     next: null,
     page: 1,
     per_page: 50,
     total_pages: 1 },
  users:
   [ { type: 'contact',
       id: '5a041896db50f992a0d4df1b',
       user_id: '24cfe3d6-fc76-4b39-993d-b2642b2336fb',
			 ..... (Full user object) ...
       custom_attributes: {} },
     { type: 'user',
       id: '59cbaaa693394ffc43250e67',
       user_id: '199',
       anonymous: false,
			 ..... (Full user object) ...
       custom_attributes: [Object] },
     { type: 'user',
       id: '58a69fae97d20491073d10fc',
       user_id: '1234',
       anonymous: false,
			 ..... (Full user object) ...
       custom_attributes: {} } ],
  total_count: 3
  }

// To get the same for segments simply replace 'tag' with 'segments'
// e.g. to get list of segments
client.segments.list(function (rsp){
    console.log(rsp.body)
});

// Returns lists of segments
{ type: 'segment.list',
  segments:
   [ { type: 'segment',
       id: '58135df83917e42135b2ea29',
       name: 'Active',
       created_at: 1477664248,
       updated_at: 1510220315,
       person_type: 'user' },
     { type: 'segment',
       id: '58135df83917e42135b2ea28',
       name: 'New',
       created_at: 1477664248,
       updated_at: 1508743608,
       person_type: 'user' },
     { type: 'segment',
       id: '59513180ac9c4dd91ec06530',
       name: 'PHILOSOPHERS',
       created_at: 1498493312,
       updated_at: 1506340076,
       person_type: 'user' },
     { type: 'segment',
       id: '58135df83917e42135b2ea2a',
       name: 'Slipping Away',
       created_at: 1477664248,
       updated_at: 1477664248,
       person_type: 'user' }] }


// And to get the list of customers in a segment
client.users.listBy({segment_id: tag_id}, function (rsp){
    console.log(rsp.body)
});
// Returns same output as tags

Creating you segments

Create your tags

🚧Use ID for leads

Find the customers you just tagged or added to a segment

Get the counts of your tag and segments

Get the customers in your tags and segments

🚧
Use ID for leads