API Connector Documentation
Import Intercom Data to Google Sheets
In this guide, we’ll walk through how to pull data from the Intercom API directly into Google Sheets, using the API Connector add-on for Google Sheets. We'll first get an API key from Intercom, and then set up a request to pull in contact and conversation data to your spreadsheet.
Contents
- Before You Begin
- Part 1: Get your Intercom API Key
- Part 2: Pull Intercom API Data into Sheets
- Part 3: More Example API URLs
- Part 4: Handle Filtering
- Part 5: Handle Pagination
- Part 6: API Documentation
Before You Begin
Click here to install the API Connector add-on from the Google Marketplace.
Part 1: Get Your Intercom API Key
- While logged into your Intercom account, navigate to the Developer Hub and click New App.
- A modal will appear, prompting you for details about your app. You can name it anything, but for this example we'll name it 'Google Sheets'. Leave the 'internal integration' radio button selected, and click Create App.
- You'll now see a page containing your Access Token. Copy this to your clipboard as you'll need it in a moment. That's it, you now have access to the Intercom API!
Part 2: Pull Intercom API Data into Sheets
For our first API request, we'll get a list of conversations. Substitute in your API key where it says your_api_key
.
- Open up Google Sheets and click Extensions > API Connector > Open > Create request.
- In the request form enter the following:
- Application:
Custom
- Method:
GET
- Request URL:
https://api.intercom.io/conversations.list?per_page=150
- Headers:
Authorization
:Bearer your_api_key
Accept
:application/json
- Application:
- Create a new tab and click Set current to use that tab as your data destination.
- Name your request and click Run. A moment later you’ll see a list of 150 recent conversations in your Google Sheet:
- (Optional) Intercom returns UNIX timestamps in the created_at and other date fields. To convert these to human-readable dates, open API Connector's field editor, click the Add formula button, and choose the "UNIX Seconds to Date" formula.
Part 3: More Example API URLs
The Intercom API provides a lot of different endpoints and functionality. Here are some examples of useful endpoints; check the documentation for the full list.
- Admins (view other users in your workspace):
https://api.intercom.io/admins
- Companies (list companies):
https://api.intercom.io/companies
- Conversations (List contacts):
https://api.intercom.io/contacts
- Counts (counts of users and companies by segment):
https://api.intercom.io/counts
- Data Attributes (attributes used to describe your customer and company models):
https://api.intercom.io/data_attributes
- Events (events belonging to a specific user. Substitute in the data.id retrieved from the /contacts endpoint):
https://api.intercom.io/events?type=user&intercom_user_id=INTERCOM_USER_ID
- Notes (view notes about users):
https://api.intercom.io/notes
- Segments (view your workspace segments):
https://api.intercom.io/segments
- Teams (view teams in your workspace):
https://api.intercom.io/teams
Part 4: Handle Filtering
- If you are filtering conversations, you can use Intercom's search endpoint as described here. In that case you'd set a POST request to
https://api.intercom.io/conversations/search
and a POST body like this:{ "query": { "field": "updated_at", "operator": ">", "value": 1560436784 } }
- Another method of filtering is through API Connector's visual field editor. Click Edit Fields before you run your request to select fields and set the column order in your sheet.
- Both filtering types can be used together. Intercom's native filtering lets you request less data from the server, which speeds up response time from the server. API Connector’s field editor only filters the data once the response has been received, which gives you better control about exactly which data gets displayed and speeds up the process of printing data into the sheet.
Part 5: Handle Pagination
Some Intercom endpoints will return a limited set of data, generally just 10 or 20 records at one time. To retrieve additional data, you can first try appending ?per_page=150
to the end of your URL to bump that up to 150 records (different endpoints have different limits).
To get more than that, you'll need to follow Intercom's instructions for handling pagination. With API Connector, you can run these as separate requests, or loop through pages automatically using pagination handling. Intercom uses different types of pagination depending on the endpoint:
- Next page URL pagination (used for most
GET
endpoints) - Cursor pagination (used for listing contacts and conversations)
- Cursor body pagination (used for most
POST
endpoints)
Next page URL pagination
- API URL: enter your request URL, including per_page=50
- Pagination type:
next page URL
- Next page path:
pages.next
- Run until: choose when to stop fetching data
Cursor pagination
- API URL:
https://api.intercom.io/contacts?per_page=150
- Pagination type:
cursor
- Next token parameter:
starting_after
- Next token path:
pages.next.starting_after
- Run until: choose when to stop fetching data
Cursor body pagination
- API URL:
https://api.intercom.io/contacts/search
- Pagination type:
cursor body
- Next token parameter:
pagination.starting_after
- Next token path:
pages.next.starting_after
- Run until: choose when to stop fetching data
Content Type
header of application/json
Part 6: API Documentation
Official API documentation: https://developers.intercom.com/intercom-api-reference/reference
Hi,
thanks for the add-on!
I try to get intercom data in a sheet and in cases when a value is unknown the columns get messed up - see eg: https://postimg.cc/fkDk6HrC
Can you provide a way around this?
OR is it just an intercom 'feature'?
PS Oddly this seems to be associated with importapi. Just outputting the results of a request with save & run maintains the column structure despite unknown values in some lines coming back.
Hi Dimitris, thanks for the message. API Connector prints out data in the order it comes back from the API, so data can switch location if an API sends back different fields between pulls. Typically this happens when a field is empty, such that the API doesn't send it at all, which shifts around all the surrounding data.
To address, you can add filtering to pull back data that always contains results or you can include a JMESPath expression to fix your fields in place.
As for IMPORTAPI vs. the sidebar, they process data the same way so I'm not sure yet why you're getting different results. It should be exactly the same. Can you please share your request URLs or your sheet with me so I can take a look?
Update: you can now use our visual field editor to easily set column order.
For the conversation connection when I run scheduled or manual request don’t finish but they also don’t give an error. It used to work, has something changed?
Nothing has changed on this side (or Intercom's side) so I suspect the issue is that you have more conversations to fetch now, and the request is timing out. If you aren't already, can you just fetch new conversations instead of the conversations you already have stored in your sheet? I think the easiest is to set your request to fetch the max (150) records each time it runs, and then use merge mode that data so that any existing records will be updated, and new records will be added.