Editor's note: This article is part of a series on building third-party API integrations. Explore Merge if you’re looking to add 180+ integrations across HR, SCIM, payroll, ATS, CRM, accounting, ticketing, marketing automation, and file storage with one unified API.

Intercom is a powerful customer communication platform that equips organizations with an array of tools for effective customer engagement and interaction. It combines functionalities such as live chat, help desk support, and customer engagement, enabling businesses to deliver personalized customer service and foster enhanced relationships. Additionally, Intercom provides an Application Programming Interface (API) for businesses to access, integrate, and manipulate their Intercom data, encompassing conversations, users, and companies.

For developers aiming to extract Conversations from a client's Intercom system, they can do so to analyze customer dialogues, optimize customer service, and gain valuable insights into customer behaviors and preferences. The Intercom API serves as an integration point allowing developers to programmatically retrieve, manage, and manipulate these Conversations. This facilitates a more efficient, data-centric approach to improving customer experience and satisfaction.

{{blog-cta-100+}}

Intercom API's authentication configuration

Intercom supports two forms of authentication -- OAuth and Basic Authentication. In this article, we will walk you through the Basic Auth method.

First, you need to find your API key. This token can be found in your Intercom settings under <code class="blog_inline-code">Access Token Management</code>.

Every request you make must include this access token in the <code class="blog_inline-code">Authorization</code> header field. The format will look like this: <code class="blog_inline-code">Authorization: Bearer YOUR_ACCESS_TOKEN</code>.

In addition to this, all requests to Intercom must include the header field <code class="blog_inline-code">Accept: application/json</code>. This specifies that the client wants the response data in JSON format. Make sure to include these header fields in all of your API requests to ensure successful communication with the Intercom API.

GET conversations from Intercom's API

Now let's get coding.

In this script below, we are making a GET request to Intercom's Conversations API endpoint. We are using the <code class="blog_inline-code">requests</code> library to send the HTTP request and the <code class="blog_inline-code">json</code> library to parse the JSON response.

The function <code class="blog_inline-code">get_conversations</code> sends a GET request to the provided URL and returns the parsed JSON response. The function <code class="blog_inline-code">extract_conversations</code> extracts the conversations from the response. We first call <code class="blog_inline-code">get_conversations</code> with the initial URL and extracts the conversations from the response.

python
import requests
import json

url = 'https://api.intercom.io/conversations'
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {API_KEY}',
}

def get_conversations(url):
    response = requests.get(url, headers=headers)
    data = json.loads(response.text)
    return data

def extract_conversations(data):
    conversations = data['conversations']
    return conversations

data = get_conversations(url)
conversations = extract_conversations(data)        

‍

Now, we start paginating through Intercom's response. The function <code class="blog_inline-code">get_next_page</code> checks if there is a next page URL in the response and returns it if there is one -- otherwise it returns <code class="blog_inline-code">None</code>. Then we enter a loop where it keeps calling <code class="blog_inline-code">get_conversations</code> with the next page URL and extracting the conversations until there are no more pages. Finally, we print all the conversation!

def get_next_page(data):
    if data['pages']['next']:
        return data['pages']['next']
    else:
        return None

next_page = get_next_page(data)
while next_page:
    data = get_conversations(next_page)
    conversations += extract_conversations(data)
    next_page = get_next_page(data)
    
for conversation in conversations:
    print(conversation)

‍

Congrats! Now you should see the list of Conversations from Intercom as the output.

{
  "type": "conversation.list",
  "pages": {
    "type": "pages",
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  },
  "total_count": 1,
  "conversations": [
    {
      "type": "conversation",
      "id": "455",
      "created_at": 1698402964,
      "updated_at": 1698402964,
      "waiting_since": null,
      "snoozed_until": null,
      "source": {
        "type": "conversation",
        "id": "403918332",
        "delivered_as": "admin_initiated",
        "subject": "",
        "body": "
this is the message body
",
        "author": {
          "type": "admin",
          "id": "991267877",
          "name": "Ciaran142 Lee",
          "email": "admin142@email.com"
        },
        "attachments": [],
        "url": null,
        "redacted": false
      },
      "contacts": {
        "type": "contact.list",
        "contacts": [
          {
            "type": "contact",
            "id": "653b92937e1c8b2e793e3678",
            "external_id": "70"
          }
        ]
      },
      "first_contact_reply": null,
      "admin_assignee_id": null,
      "team_assignee_id": null,
      "open": false,
      "state": "closed",
      "read": false,
      "tags": {
        "type": "tag.list",
        "tags": []
      },
      "priority": "not_priority",
      "sla_applied": null,
      "statistics": null,
      "conversation_rating": null,
      "teammates": null,
      "title": null,
      "custom_attributes": {},
      "topics": {},
      "ticket": null,
      "linked_objects": {
        "type": "list",
        "data": [],
        "total_count": 0,
        "has_more": false
      }
    }
  ]
}

‍

Conclusion

Wasn't that fun? Now you can keep building!

Unfortunately, Intercom is probably only one of many integrations in the help desk / ticketing space that your team must integrate with.

This is where a Unified API, such as Merge, comes into play. At Merge, we’ve built an API that lets you easily integrate once to offer 30+ Ticketing, Project Management and Helpdesk integrations. Our Unified API fully normalizes authentication, pagination, rate limits and response bodies.‍

Learn more about Merge by scheduling a demo!