Extract your data from Intercom

Intercom exposes a rich REST API for interacting with its services. There are two reasons someone would like to use the Intercom REST API:

1. To pull data from it and use it for analytic purposes.
2. To push data to enrich the information it contains for customers and enhance its service.

This post will focus mainly on pulling data from the API and using it to enrich our data warehouse with data generated from our interactions with our customers.

The main entities of the Intercom API are the following:

• Users – a primary way of interacting with Intercom.
• Leads – represent logged-out users of your application.
• Companies – allow you to represent commercial organizations using your product.
• Tags – A tag allows you to label your users and companies and list them using that tag.
• Segments – A segment is a group of your users defined by rules that you set.
• Notes – Notes allow you to annotate and comment on your users.
• Events – Events are how you can submit user activity to Intercom.
• Counts – You can get counts of users and companies filtered by specific criteria.
• Conversations – Conversations are how you can communicate with users in Intercom.

Note that you cannot pull out all of the above entities from the Intercom API. For example, you can push Events inside Intercom; however, it’s challenging to extract them again. So if you plan to use Intercom to track your users’ behavior, keep that in mind because contrary to services like Mixpanel, it’s not possible to pull the user events from the system. An excellent strategy to ensure that your user activity is pushed on all the different services and that you will always have access to the data is to use a service like RudderStack.

Intercom Exposes a RESTful Web API, which means that we interact with its resources through HTTP verbs like POST and GET by using an HTTP client. Intercom also offers several SDKs built around an HTTP client for a number of popular languages:

• PHP
• Node
• Ruby
• Rails
• Go
• Java

Pull Data From the Intercom REST API

To pull your data out of Intercom you need to fetch all your users together with all their conversations. You can then load this information to your data warehouse and enhance your analytic capabilities with other interactions with them. To do that, you first need to get all your users, with CURL, in the following way:

SH
Copy
curl https://api.intercom.io/users -u pi3243fa:da39a3ee5e6b4b0d3255bfef95601890afd80709 -H 'Accept: application/json'

A typical result will look like this:

JSON
Copy
{ "type": "user.list", "total_count": 105, "users": [ { "type": "user", "id": "530370b477ad7120001d", ... }, ... ], "pages": { "next": "https://api.intercom.io/users?per_page=50&page=2", "page": 1, "per_page": 50, "total_pages": 3 } }

Now we can also extract a full list of the conversations that have been performed on Intercom by using the following command:

SH
Copy
$ curl https://api.intercom.io/conversations?type=admin&admin_id=25&open=true -u pi3243fa:da39a3ee5e6b4b0d3255bfef95601890afd80709 -H 'Accept:application/json'

and a typical result will look like the following:

JSON
Copy
{ "type": "conversation.list", "conversations": [ { "type": "conversation", "id": "147", "created_at": 1400850973, "updated_at": 1400857494, "user": { "type": "user", "id": "536e564f316c83104c000020" }, "assignee": { "type": "admin", "id": "25" }, "conversation_message": { "type": "conversation_message", "subject": "", "body": "<p>Hi Alice,</p>nn<p>We noticed you using our Product, do you have any questions?</p> n<p>- Jane</p>", "author": { "type": "admin", "id": "25" }, "attachments": [ { "name": "signature", "url": "https://someurl.com/signature.jpg" } ] } } ] }

As we can see, each conversation contains a user object which contains an id. In this way, we can associate the conversations with the users we had extracted earlier. Of course, to do that on our Data warehouse repository, we need to map the above structures to the data model that the repository follows by respecting both the schema and the data types. Next, we can write a pipeline that will extract the data and transform it into our repository model and load the data by following the instructions that follow below. Of course, if something changes on the Intercom API, the pipeline will break, and we will have to take care of it.

Use Webhooks to Push Events from Intercom to Your Data Warehouse

Intercom also supports the definition of webhooks, where you can register certain events, and the system will push there a message whenever the event is triggered. For example, you might define a webhook that will push a message for all new conversations initiated with your customers. By doing this, it is possible to create a near real-time streaming load process for your data warehouse. To implement something like that, though, you need to consider the limitations of both ends while ensuring the delivery semantics that your use case requires for the data management infrastructure that you will build.

For more information, you can check the webhooks section on the Intercom API documentation.

Prepare your Intercom Data for Google BigQuery

Before you load your data into BigQuery, you should make sure that it is presented in a format supported by it. For example, if the API you pull data from returns XML, you must first transform it into a serialization that BigQuery understands. Currently, two data formats are supported:

• CSV
• JSON

You also need to make sure that the data types you are using are the ones supported by BigQuery, which are the following:

• STRING
• INTEGER
• FLOAT
• BOOLEAN
• RECORD
• TIMESTAMP

for more information please check the Preparing Data for BigQuery page on the documentation.

Load Intercom Data to Google BigQuery

If you want to load Intercom data to Google BigQuery, you have to use one of the following supported data sources:

1. Google Cloud Storage
2. Sent data directly to BigQuery with a POST request
3. Google Cloud Datastore Backup
4. Streaming insert
5. App Engine log files
6. Cloud Storage logs

From the above list of sources, 5 and 6 are not applicable in our case.

For Google Cloud Storage, you first have to load your data into it, there are a few options on how to do this, for example, you can use the console directly as described here and do not forget to follow the best practices. Another option is to post your data through the JSON API, as we see again APIs play an important role in both the extraction but also the loading of data into our data warehouse. In it’s simplest case it’s just a matter of one HTTP POST request using a tool like CURL or Postman. It should look like the following example:

SH
Copy
POST /upload/storage/v1/b/myBucket/o?uploadType=media&name=myObject HTTP/1.1 Host: www.googleapis.com Content-Type: application/text Content-Length: number_of_bytes_in_file Authorization: Bearer your_auth_token your Intercom data

and if everything went ok, you should get something like the following as a response from the server:

SH
Copy
HTTP/1.1 200 Content-Type: application/json { "name": "myObject" }

Working with Curl or Postman is good only for testing, if you would like to automate the process of loading your data into Google Bigquery, you should write some code to send your data to Google Cloud Storage. In case you are developing on the Google App Engine you can use the library that is available for the languages that it supports:

• Python
• Java
• PHP
• Go

If you are using one of the above languages and are not coding for the Google App Engine, you can access the Cloud Storage from your environment. Interacting such a feature-rich product like Google Cloud Storage can become quite complicated depending on your use case. For more details on the different options that exist, you can check Google Cloud Storage documentation. If you are looking for a less engaged and more neutral way of using Cloud Storage, you can consider a solution like RudderStack.

After you have loaded your data into Google Cloud Storage, you have to create a Load Job for BigQuery to load the data into it. This Job should point to the source data in Cloud Storage that have to be imported, and this happens by providing source URIs that point to the appropriate objects.

The previous method described a POST request to the Google Cloud Storage API for storing the data there and then loading it into BigQuery. Another way to go is to make a direct HTTP POST request to BigQuery with the data you would like to query. This approach is similar to how we loaded the data to Google Cloud Storage through the JSON API, but it uses the appropriate end-points of BigQuery to load the data there directly. The way to interact with it is quite similar, for more information can be found on the Google BigQuery API Reference and on the page that describes how to load data into BigQuery using POST. You can interact with it using the HTTP client library of the language or framework of your choice, a few options are:

• Apache HttpClient for Java
• Spray-client for Scala
• Hyper for Rust
• Ruby rest-client
• Python HTTP-client

The best way to load data from Intercom to Google BigQuery and possible alternatives

So far, we have looked at some basic implementations with Google BigQuery and how to load data into it. The way to proceed relies heavily on the data you want to load, from which service they are coming from, and your use case’s requirements. Things can get even more complicated if you’re going to integrate data coming from different sources. Instead of writing, hosting, and maintaining a flexible data infrastructure, a possible alternative is to use RudderStack that can handle this kind of problem automatically for you.

RudderStack integrates with multiple sources or services like databases, CRM, email campaigns, analytics, and more. Quickly and safely move all your data from the Intercom into your data warehouse and start generating insights from your data.