How to load data from Intercom to Google BigQuery

Blendo Team

So, you decided you want to analyze the data you have on Intercom and do that on  Google BigQuery. The purpose of this post is to help you define a pipeline, to load data from Intercom to Google BigQuery for further analysis. Alternatively, in order to you can use an ETL as a service product like Blendo that can handle this kind of problems automatically for you.

Information will be given on how to access and extract your data from Intercom through its API and how to load it into BigQuery, this process requires from you to write the code to get the data and make sure that this process will run every time new data are generated.

What we will see:

  • An Intro to Google BigQuery and Intercom.
  • Extract your data from Intercom and Intercom API (the hard way)
  • Prepare your Intercom Data for Google BigQuery
  • Load Data from Intercom to Google BigQuery
  • The best way to load data from Intercom to Google BigQuery (the easy way)

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 into to to enrich the information it contains for customers and enhance its service

At this post we’ll focus mainly on pulling data from the API and use it to enrich our data warehouse with data that are generated from our interactions with our customers.

The main entities of the Intercom API are the following:

  • Users – which is the 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 certain criteria.
  • Conversations – Conversation are how you can communicate with users in Intercom.

At this point it has to be noted that not all of the above entities can be pulled out from the Intercom API. For example, Events can only be pushed inside Intercom and it’s not possible to extract them again. So if you plan to use Intercom also for tracking the behavior of your users keep that in mind, because contrary to services like Mixpanel, it’s not possible to pull the user events from the system. A good strategy for ensuring that your user activity will be pushed on all the different services that you need and that you will always have access to the data is by using a service like Segment.

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 a number of SDKs that are build around an http client for a number of popular languages:

You will need more time to read this post than integrating Intercom to BigQuery.

Effortlessly Sync All Your Intercom Data to BigQuery

Pull data from the Intercom REST API

A typical use case for pulling data out of Intercom is to fetch all your users together with all the conversations you have done with each one. Then you can load this information to your data warehouse and enhance your analytic capabilities with additional interactions that you had with them. To do that you first need to get all your users, with CURL you can do that in the following way:

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

A typical result will look like this:

{ "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 doing the following:

$ 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:

{ "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 in order 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. Then we can write a pipeline that will extract the data and transform it into the model of our repository 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 events is triggered. So for example you might define a webhook that will push a message every time a new conversation is performed with your customers. By doing this it is possible to create a near real time streaming load process on for your data warehouse. In order to implement something like that though, you need to take into consideration the limitations of both ends, while ensuring that 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.

About Intercom

Intercom is a fundamentally new way to communicate with your customers. It is one place for every team in an internet business to communicate with customers, personally, at scale – on your website, inside web and and mobile apps, and by email. It offers four products.

  • Acquire – which helps you to communicate with your customers by chatting with them

  • Engage – which helps you to onboard and retain your customers with targeted emails and in-app messages

  • Learn – which helps you to get feedback from your customers more effectively

  • Support – which helps you to support your customers from inside your application

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, so for example if the API you pull data from returns XML you have to first transform it into a serialization that BigQuery understands. Currently two data formats are supported:

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.

About Google BigQuery

BigQuery is the data warehousing solution of Google. It’s part of the Google Cloud Platform and it also speaks SQL like Redshift does. Queries are executed against append-only tables using the processing power of Google’s infrastructure. It is also fully managed and is offered as a service over the cloud. You can interact with it through its web UI, using a command line tool while a variety of client libraries exist so you can interact with it through your application.

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 it is 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.

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:

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 are supported by it:

  1. Python
  2. Java
  3. PHP
  4. Go

If you are using one of the above languages and you are not coding for the Google App Engine, you can use it to 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 Blendo.

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

The previous method described, used a POST request to the Google Cloud Storage API for storing the data there and then load it into BigQuery. Another way to go is to do 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:

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

So far we just scraped the surface of what can be done 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 the requirements of your use case. Things can get even more complicated if you want to integrate data coming from different sources. A possible alternative, instead of writing, hosting and maintaining a flexible data infrastructure, is to use an ETL as a service product like Blendo that can handle this kind of problems automatically for you.

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

 

 

Help your customer success and executive team take ownership of the insights of your customers' interactions data that live in Intercom to transform customer satisfaction.

Blendo is the easiest way to automate powerful data integrations.

Try Blendo free for 14 days. No credit card required.