Creating users
Adding user data
After signing up for an Intercom account, the first thing you'll need in the Platform is users - they're the main data source in Intercom. The Platform allows you to store data on your users, including events, and use this data to segment and understand them in more detail.
You can then use the Intercom products to speak with those users, be it for support, announcements or to get feedback. Understanding the Platform and how it works will enable you to realize the full potential of the features available with the Intercom products. So, let’s get some data into the Platform so we can start using it.
Importing your users
If you're importing your users for the first time, then it's likely you have a CSV file containing your current user data (or you can easily migrate your data to this format). You can import your users via a CSV on the website or through some of the other means described here. However, you can also import users via the REST API and that is going to be the focus for this tutorial.
Writing or running code examples
If you used the Docker setup or you downloaded the code from Github, then you should have all the code you will create in the series already. You can just run the commands if you like, rather then re-writing the code; every section will have some code to write and then some commands to execute, so you can just skip to the commands.
However, remember that we're building up the code as we move through the tutorial series, so this may be confusing if you see code that you have not used yet in the series. We therefore recommend that you create the code as you move through the tutorial to make it easier to follow.
Initializing your client
First, let’s create a single user in your Intercom Platform. This is just to get an idea of how the process works and then we can bulk import the rest of your users.
The first step is to create a new directory where we can add our new code, which will use the Ruby SDK. As we noted in the setup section, you can clone the code for these tutorials or you can create a directory and create the code as we work through it here.
After setting up your working directory (let's refer to this as your tasks directory from now on), the next thing we want to do is initialize your client so that we can access the data in your app. Let's create a separate function for this so that we can easily reference it later in a different file.
Create a file called intercom_client.rb and add the following code to it:
require 'intercom'
class IntercomClient
#First lets setup the client with your App ID and App Key
def initialize(your_token)
@@intercom = Intercom::Client.new(token: your_token)
end
end
We're making the intercom client a class variable by marking it with @@. We'll be able to include this code in later examples so that we don't have to initialize the client each time we use a different file. Let's include the new file we created and initialize it with your App ID and API Key:
irb> require './intercom_client'
=> true
irb> intercom = IntercomClient.new(<YOUR-ACCESS-TOKEN>)
=> #<IntercomClient:0x00000001339a90>
We could use the Ruby SDK to directly create a new user, but let's say you want to re-use the create user functionality. Instead of having to write out the SDK commands, you can create a new class and add a method to create users. Then you could add more functions for other user-defined tasks, making it easier to call these functions later from another program.
Add a single user
Now we can create a new file in the tasks directory called user_tasks.rb and add the following code to it:
require './intercom_client'
class UserTasks < IntercomClient
def initialize()
end
def create_user(args)
#Create a new user with list of values passed on setup
user = @@intercom.users.create(args)
end
end
Then in IRB (you can exit out of your previous IRB sessions and start a new one to make it easier to run any code you have changed):
require './user_tasks' #no need to require intercom_client as it is included here
intercom = IntercomClient.new(<YOUR-ACCESS-TOKEN>)
user = UserTasks.new()
user.create_user(:email => "[email protected]", :user_id => 1)
In the above example we only created a user with an email and user ID. However, you can also create users with more details, such as the time the user signed up:
user.create_user(:email => "[email protected]", :user_id => 2, :name => "Aristotle", :signed_up_at => Time.now.to_i)
Finding a user
You should be able to search for a user once you've added them in the Platform. You can search via email or user_id. In the SDK we note there are 3 ways to search for a user. Note that the id field below is automatically generated when a user is created.
You can use it in the same way as the other fields:
# Find user by email
user = intercom.users.find(:email => "[email protected]")
# Find user by user_id
user = intercom.users.find(:user_id => "1")
# Find user by id
user = intercom.users.find(:id => "571921c8cbc37c3717000003")
However, since we already have a user class and one method, we can create a new one to do these 3 functions in one go for us. So, in your user_tasks.rb file add in the following code for the find_user.rb method. Your file should now look like the code in user_tasks.rb:
def find_user(criteria)
begin
#Check for users via the unique ID
user = @@intercom.users.find(:id => criteria)
rescue Intercom::ResourceNotFound
begin
#Check for users via user id if we receive not found error
user = @@intercom.users.find(:user_id=> criteria)
rescue Intercom::ResourceNotFound
#Check for users via email address
user = @@intercom.users.find(:email => criteria)
end
end
end
require './intercom_client'
class UserTasks < IntercomClient
def initialize()
end
def create_user(args)
#Create a new user with list of values passed on setup
user = @@intercom.users.create(args)
end
def find_user(criteria)
begin
#Check for users via the unique ID
user = @@intercom.users.find(:id => criteria)
rescue Intercom::ResourceNotFound
begin
#Check for users via user id if we receive not found error
user = @@intercom.users.find(:user_id=> criteria)
rescue Intercom::ResourceNotFound
#Check for users via email address
user = @@intercom.users.find(:email => criteria)
end
end
end
end
We are using the exception returned by the search to see if we need to continue searching. This way we do not need to check what element has been passed through. It makes our user_tasks.rb function a little more useful. Let's find a user:
> usr = user.find_user("[email protected]")
Intercom::ResourceNotFound: User Not Found
> usr = user.find_user("[email protected]")
=> #<Intercom::User:0x00000002a881d8
> usr.email
=> "[email protected]"
> usr.user_id
=> "1"
> usr.id
=> "5718e23e722c6465b6000081"
usr = user.find_user(1)
=> #<Intercom::User:0x00000001fea4b0
> usr.email
=> "[email protected]"
> usr = user.find_user("5718de24722c64be14000176")
=> #<Intercom::User:0x00000001fe1a90
> usr.id
=> "5718de24722c64be14000176"
> usr.email
=> "[email protected]"
In the first case we got an error since there was no corresponding user. However, when we search for one that is in our Platform we get a result. You can then look at the attributes of this object to try and see some of our user values, such as email and user_id. You can search using other criteria as well.
Great! Now that we've learnt how to create users, let's move on to learning about tags so that we can easily group them.
Updated over 6 years ago