API Changelog

Unstable

Unstable Version

This version is not stable and everything within is subject to change. We recommend using this for test and staging environments, as opposed to within production.

Export Message data through our API

You can use the API to export data for all messages sent in a given timeframe. This data will be valuable in analysing the performance of your messages or joining message engagement data with user data external to Intercom to attribute performance. You can see the three operations you'll have to perform to retrieve this in our reference.

1.3

Introducing Canvas Kit

Say hello to a quicker and easier way to build contextual and action-oriented apps embedded into Intercom's UI. With the launch of Canvas Kit, you keep all the capabilities of embedding apps in the Messenger, and gain:

Capbilities for emebedding apps in Inbox - you can now build apps for the conversation details within Intercom's Inbox product. Take a look at our revampped Canvas Kit guides to understand just how easy it is.
New Components - to make it easy to display data and input larger voucher, we've launched Data Table and Text Area components.
Canvas Kit Builder - preview the JSON of your app to see what it will look like and how people can interact with it. The Builder is embedded throuhgout the docs but can also be accessed here.

Removing the users object from Canvas Kit request payloads

Instead of sending a users object within Canvas Kit requests, we now send a customer object instead. This returns exactly the same payload but also includes leads.

Removing the app_id key from Canvas Kit request payloads

Instead of sending an app_id key within Canvas Kit requests, we now send a workspace key instead. This returns exactly the same information as the value.

Adding an author object to Conversation payloads

We now return an author object within Conversation and Conversation Part objects sent throughout our REST API responses and Canvas Kit requests. This will contain the name and email of the message's author.

Preventing null for unsubscribed_from_emails

The API will now return an error if unsubscribed_from_emails is set to null for User requests.

1.2

Removing personally identifiable information (PII) from our API & Webhooks

Across our API & Webhooks, we will no longer return the last_seen_ip, location_data.longitude, location_data.latitude, and user_agent_data for users, leads, and visitors. This is part of an effort to keep customers data secure and uphold the availability of Intercom across services that require such information to not be exposed.

View activity logs for admins through our API

You can now get a log of activities taken by all admins in an app through our API. Simply send a GET request to https://api.intercom.io/admins/activity_logs. You can see request, params, and responses on our reference.

Set waiting since attribute to null for admin replies

In previous versions of our API, the value of the waiting_since attribute on the Conversation model is set to 2000 years in the future if the last reply is from an admin. This change sets the value of waiting_since to null instead.

List users by email returns users only

Previously, the list users by email endpoint returned a list of users and contacts. It will now return users only.

Allow contacts to be viewed/listed by phone

Previously, the you could list contacts by email only. Now you can also list them by phone.

New Conversations Part Redacted Webhook

There is a new webhook which fires when a conversation part is redacted.

New Conversations Rating Added Webhook

There is a new webhook which fires when a rating is added to a conversation.

1.1

The full list of changes in this version is:

Users endpoint - Find multiple users via email
Conversations endpoint - Adding more information for the user's first reply
Messenger framework - new_canvas no longer accepted
Messenger framework - Disable component option
Webhooks - Four new webhook topics added

Breaking change

Note that this version includes a breaking change to the API and may require a code change if you are using this feature:
users endpoint - search via email, we now returns a list with zero or more entries, whereas previously it returned a user object
Messenger framework - new_canvas no longer accepted

Users endpoint - Find multiple users via email

Previously if you searched for a user via email it would return an error if more than one user existed with the email. It returned a user object. Now it will return the same list object as with list users.

curl https://api.intercom.io/users?email=test@test.com \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Accept: application/json' \
-H 'Intercom-Version: 1.1'

{
    "limited": false,
    "pages": {
        "next": null,
        "page": 1,
        "per_page": 50,
        "total_pages": 1,
        "type": "pages"
    },
    "total_count": 3,
    "type": "user.list",
    "users": [
        {
            "anonymous": false,
            "app_id": "fyq3wodw",
            "created_at": 1506339558,
            "custom_attributes": {},
            "do_not_track": null,
            "email": "test@test.com",
            "has_hard_bounced": false,
            "id": "45c8eae6fac10f5584e7508e",
            "last_request_at": 1529737920,
            "last_seen_ip": "78.144.182.179",
            ....
            ....
        },
        {
            "anonymous": true,
            "app_id": "fyq3wodw",
            "created_at": 1503488750,
            "custom_attributes": {},
            "do_not_track": null,
            "email": "test@test.com",
            "has_hard_bounced": false,
            "id": "5123d6aeeda850883ed8ba7c2",
            "last_request_at": 1503488749,
            ....
            ....
        },
        {
            "anonymous": false,
            "app_id": "fyq3wodw",
            "created_at": 1494940172,
            "custom_attributes": {},
            "do_not_track": null,
            "email": "test@test.com",
            "has_hard_bounced": false,
            "id": "789afa0cb781d52fd3044ecc",
            "last_request_at": 1494940211,
            ....
            ....
        }
    ]
}

{
    "limited": false,
    "pages": {
        "next": null,
        "page": 1,
        "per_page": 50,
        "total_pages": 1,
        "type": "pages"
    },
    "total_count": 3,
    "type": "user.list",
    "users": [
        {
            "anonymous": false,
            "app_id": "fyq3wodw",
            "created_at": 1506339558,
            "custom_attributes": {},
            "do_not_track": null,
            "email": "test@test.com",
            "has_hard_bounced": false,
            "id": "45c8eae6fac10f5584e7508e",
            "last_request_at": 1529737920,
            "last_seen_ip": "78.144.182.179",
            ....
            ....
        },
        {
            "anonymous": true,
            "app_id": "fyq3wodw",
            "created_at": 1503488750,
            "custom_attributes": {},
            "do_not_track": null,
            "email": "test@test.com",
            "has_hard_bounced": false,
            "id": "5123d6aeeda850883ed8ba7c2",
            "last_request_at": 1503488749,
            ....
            ....
        },
        {
            "anonymous": false,
            "app_id": "fyq3wodw",
            "created_at": 1494940172,
            "custom_attributes": {},
            "do_not_track": null,
            "email": "test@test.com",
            "has_hard_bounced": false,
            "id": "789afa0cb781d52fd3044ecc",
            "last_request_at": 1494940211,
            ....
            ....
        }
    ]
}

{
    "limited": false,
    "pages": {
        "next": null,
        "page": 1,
        "per_page": 50,
        "total_pages": 0,
        "type": "pages"
    },
    "total_count": 0,
    "type": "user.list",
    "users": []
}

Conversations endpoint - Adding more information for user's first reply

It is now possible to get more information about your users first response. Customer have asked for this feature so they can better understand key metrics which may help identify patterns around what encouraged your customers to reply to a particular message. Similarly, it will also allow you to prioritise messages based on whether they were delivered as Auto-Messages, Bot messages or Manual Messages for example.

The new information will be available in the conversation model object returned when you list your conversations. It will contain:

Source URL - The URL for the page from where your customer replied. This will not be available in all cases, e.g. when a customer replies via email.
Channel - The channel the replay occurred within e.g. via email, in a conversation or via a 3rd party integration such as twitter or facebook
Created at time - The time the users response was created
How was the original message delivered - Was it an Auto-Message or a Campaigns Message or a Manual Message for example.

Conversation list

There is no change to how your list conversations. We have just added some new attributes to the conversation model returned.

New or updated Attributes

The conversation model will include the follow new attributes

Attribute

Type

Description

customer_first_reply

Object

An object containing information on the first users message. For a user initiated message this will represent the users original message.

type

String

This has been updated and now includes conversation, push, facebook, twitter and email

delivered_as

String

How was the message delivered by Intercom. They types of delivery are customer_initiated, automated, campaigns_initiated, admin_initiated, and operator_initiated.

"delivered_as" message types explained

customer_initiated means this message was delivered as a user initiated message
automated means the message was delivered as either a visitor auto message or an automated message
campaigns_initiated means the message was delivered as a campaigns message
operator_initiated means the message was delivered as a bot auto message
admin_initiated means the message was delivered as an admin initiated message

Customer First reply model

Attribute

Type

Description

Channel

String

Over which channel did the first reply occur. Options include conversation, push, facebook, twitter and email

URL

String

The URL where the first reply originated from. In some cases, e.g. email replies this will be blank.

Created_at

Timestamp

The time the users messages was created. This is in unix timestamp format

"customer_first_reply" set to null

If a user has not replied to an Intercom initiated message (e.g. auto messages, admin initiated messages, campaigns) then the customer_first_reply attribute will be null

# You still list conversations in the same way. The only change is there are some new attributes added as part of the conversation message.
curl "https://api.intercom.io/conversations" \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Accept: application/json' \
-H 'Intercom-Version: 1.1'

{
 "conversations": [
 {
 "assignee": {
 "id": null,
 "type": "nobody_admin"
 },
 "conversation_message": {
 "attachments": [],
 "author": {
 "id": "5bd155b5d8b61587a0203f31",
 "type": "lead"
 },
 "body": "\ud83d\ude00",
 "delivered_as": "customer_initiated",
 "id": "271978806",
 "subject": "",
 "type": "conversation",
 "url": "https://s.codepen.io/test/app"
 },
 "created_at": 1540449375,
 "customer_first_reply": null,
 "customers": [
 {
 "id": "5bd112b5d8b61534a0203f12",
 "type": "lead"
 }
 ],
 "first_action_at": 1540449375,
 "id": "19205537453",
 "last_action_at": 1540449378,
 "open": true,
 "read": true,
 "sent_at": 1540449378,
 "snoozed_until": null,
 "state": "open",
 "type": "conversation",
 "updated_at": 1540449379,
 "user": {
 "id": "5bd112b5d8b61534a0203f12",
 "type": "lead"
 },
 "waiting_since": 1540449375
 },
 ...
 ...
 ...
 ],
 "pages": {
 "next": "https://api.intercom.io/conversations?per_page=20&page=2",
 "page": 1,
 "per_page": 20,
 "total_pages": 76,
 "type": "pages"
 },
 "type": "conversation.list"
}

{
    "conversations": [
        {
            "assignee": {
                "id": null,
                "type": "nobody_admin"
            },
            "conversation_message": {
                "attachments": [],
                "author": {
                    "id": "5bd155b5d8b61587a0203f31",
                    "type": "lead"
                },
                "body": "<p>\ud83d\ude00</p>",
                "delivered_as": "customer_initiated",
                "id": "271978806",
                "subject": "",
                "type": "conversation",
                "url": "https://s.codepen.io/test/app"
            },
            "created_at": 1540449375,
            "customer_first_reply": null,
            "customers": [
                {
                    "id": "5bd112b5d8b61534a0203f12",
                    "type": "lead"
                }
            ],
            "first_action_at": 1540449375,
            "id": "19205537453",
            "last_action_at": 1540449378,
            "open": true,
            "read": true,
            "sent_at": 1540449378,
            "snoozed_until": null,
            "state": "open",
            "type": "conversation",
            "updated_at": 1540449379,
            "user": {
                "id": "5bd112b5d8b61534a0203f12",
                "type": "lead"
            },
            "waiting_since": 1540449375
        },
        ...
        ...
        ...
            ],
    "pages": {
        "next": "https://api.intercom.io/conversations?per_page=20&page=2",
        "page": 1,
        "per_page": 20,
        "total_pages": 76,
        "type": "pages"
    },
    "type": "conversation.list"
}

{
 "conversations": [
 {
 "assignee": {
 "id": null,
 "type": "nobody_admin"
 },
 "conversation_message": {
 "attachments": [],
 "author": {
 "id": "814865",
 "type": "admin"
 },
 "body": "Hi \ud83d\ude00 We hope you enjoy the example app. To get started just copy and paste some code into the JS editor. Let us know if you think this is useful? ",
 "id": "55951247",
 "subject": "",
 "type": "conversation_message",
 "url": null
 },
 "created_at": 1540314098,
 "customers": [
 {
 "id": "1234bea776767676676bae2334",
 "type": "lead"
 }
 ],
 "first_action_at": 1540314131,
 "id": "19179279317",
 "last_action_at": 1540314133,
 "open": true,
 "read": true,
 "sent_at": 1540314133,
 "snoozed_until": null,
 "state": "open",
 "type": "conversation",
 "updated_at": 1540314134,
 "user": {
 "id": "aa444f2314fe1334r345",
 "type": "lead"
 },
 "waiting_since": 1540314131
 },
 ...
 ...
 ],
 "pages": {
 "next": "https://api.intercom.io/conversations?per_page=20&page=2",
 "page": 1,
 "per_page": 20,
 "total_pages": 15,
 "type": "pages"
 },
 "type": "conversation.list"
}

{
    "conversations": [
        {
            "assignee": {
                "id": null,
                "type": "nobody_admin"
            },
            "conversation_message": {
                "attachments": [],
                "author": {
                    "id": "814865",
                    "type": "admin"
                },
                "body": "<p>Hi \ud83d\ude00 We hope you enjoy the example app. To get started just copy and paste some code into the JS editor. Let us know if you think this is useful? <br></p>",
                "id": "55951247",
                "subject": "",
                "type": "conversation_message",
                "url": null
            },
            "created_at": 1540314098,
            "customers": [
                {
                    "id": "1234bea776767676676bae2334",
                    "type": "lead"
                }
            ],
            "first_action_at": 1540314131,
            "id": "19179279317",
            "last_action_at": 1540314133,
            "open": true,
            "read": true,
            "sent_at": 1540314133,
            "snoozed_until": null,
            "state": "open",
            "type": "conversation",
            "updated_at": 1540314134,
            "user": {
                "id": "aa444f2314fe1334r345",
                "type": "lead"
            },
            "waiting_since": 1540314131
        },
        ...
        ...
            ],
    "pages": {
        "next": "https://api.intercom.io/conversations?per_page=20&page=2",
        "page": 1,
        "per_page": 20,
        "total_pages": 15,
        "type": "pages"
    },
    "type": "conversation.list"
}

Messenger framework - `new_canvas` no longer accepted

During the beta launch of the Messenger framework we accepted both new_canvas and canvas as valid names for the canvas object returned to Intercom during the request flows. The new_canvas name is no longer accepted as a valid name for the canvas object.

Messenger framework - Disable component option

This version includes the ability to disable certain messenger framework components. This allows you to prevent certain components, such as elements in a list, from being selected. This may occur when customers are signed up to certain packages and have restricted options for some categories. The components which you can now disable are:

Input
Button
List + each list item
Dropdown + each dropdown option
Single Select + each single select option
For each of the above components it simply adds one optional boolean parameter which can be set to identify whether this component should be disabled or not

Attribute

Type

Required

Description

disabled

Boolean

No

'true' indicates the component is disabled. This is set to 'false' by default.

{
  "type":  "button",
  "id": "button-123",
  "label": "Submit form",
  "style": "secondary",
  "disabled": true,
  "action": {
    "type": "url",
    "url": "https://www.intercom.com/"
  }
}

{
  "type": "list",
  "items": [
    {
      "type": "item",
      "id": "article-123",
      "title": "How to install the messenger",
      "subtitle": "An article explaining how to integrate Intercom",
      "image": "http://somesite.com/article.png",
      "image_width": 48,
      "image_height": 48,
      "roundedImage": false,
      "action": {
        "type": "submit"
      }
    },
    {
      "type": "item",
      "id": "article-133",
      "title": "How to un-install the messenger",
      "subtitle": "An article explaining how to uninstall Intercom integrations",
      "image": "http://somesite.com/article2.png",
      "image_width": 48,
      "image_height": 48,
      "roundedImage": false,
      "disabled": true,
      "action": {
        "type": "submit"
      }
    }
  ]
}

New webhook topics

This version includes a number of new webhook topics to which you can now subscribe. The new topics are described in the table below. To find out more about webhooks and learn how to subscribe to these topics please see our Setting up Webhooks page.

Topic

Item Type

Description

conversation.admin.snoozed

Conversation

Subscribe to admin conversation snoozes

conversation.admin.unsnoozed

Conversation

Subscribe to admin conversation unsnoozes

contact.tag.created

ContactTag

Subscribe to leads being tagged.

contact.tag.deleted

ContactTag

Subscribe to leads being tagged.

1.0 - Original

This is the base version of the API that existed before versioning was introduced.

Building Apps

Search results for "{{ search.query }}"

API Changelog

Unstable Version

Export Message data through our API

Introducing Canvas Kit

Removing the users object from Canvas Kit request payloads

Removing the app_id key from Canvas Kit request payloads

Adding an author object to Conversation payloads

Preventing null for unsubscribed_from_emails

Removing personally identifiable information (PII) from our API & Webhooks

View activity logs for admins through our API

Set waiting since attribute to null for admin replies

List users by email returns users only

Allow contacts to be viewed/listed by phone

New Conversations Part Redacted Webhook

New Conversations Rating Added Webhook

Breaking change

Users endpoint - Find multiple users via email

Conversations endpoint - Adding more information for user's first reply

Conversation list

New or updated Attributes

"delivered_as" message types explained

Customer First reply model

"customer_first_reply" set to null

Messenger framework - `new_canvas` no longer accepted

Messenger framework - Disable component option

New webhook topics

API Changelog

Suggested Edits are limited on API Reference Pages

Unstable Version

Export Message data through our API

Introducing Canvas Kit

Removing the users object from Canvas Kit request payloads

Removing the app_id key from Canvas Kit request payloads

Adding an author object to Conversation payloads

Preventing null for unsubscribed_from_emails

Removing personally identifiable information (PII) from our API & Webhooks

View activity logs for admins through our API

Set waiting since attribute to null for admin replies

List users by email returns users only

Allow contacts to be viewed/listed by phone

New Conversations Part Redacted Webhook

New Conversations Rating Added Webhook

Breaking change

Users endpoint - Find multiple users via email

Conversations endpoint - Adding more information for user's first reply

Conversation list

New or updated Attributes

"delivered_as" message types explained

Customer First reply model

"customer_first_reply" set to null

Messenger framework - new_canvas no longer accepted

Messenger framework - Disable component option

New webhook topics

Messenger framework - `new_canvas` no longer accepted