Intercom docs

Table of contents

Getting Started

The Intercom API is based on REST: it is comprised of resources with predictable urls and utilises standard HTTP features (like HTTP Basic Authentication, Response Codes and Methods). All requests, including errors, return JSON. The API expects JSON for all POST and PUT requests.

API Endpoint

https://api.intercom.io/v1/

API Resources

  • /users
  • /users/notes
  • /users/impressions
  • /users/message_threads
  • /tags

Client/Framework Libraries

3rd party libraries

Response Codes & Errors

Intercom uses standard HTTP response codes to indicate whether a request was successful or not. All errors return a JSON object describing the error.

Successful Responses

  • 200 OK - Everything worked as expected.
  • 201 Created - Everything worked and the request resulted in a resource being created and/or updated.

Errors

  • 400 Bad Request - Often missing a required parameter.
  • 401 Unauthorized - No valid API Key provided.
  • 402 Request Failed - Parameters were valid but request failed.
  • 404 Not Found - The requested item doesn't exist.
  • 500, 502, 503, 504 Server errors - something went wrong on Intercom's end.

JSON Error Objects

{
  "error": {
    "type": "not_found",
    "message": "The User was not found"
  }
}

type can be one of:

  • not_found: The resource wasn't found
  • server_error: Something went wrong on our end

message should be a human friendly description of what went wrong.

Authentication

HTTP Authentication is used to authenticate with The API. Your username is your App ID and your password is an active API key for your app; these are both available on the API keys page, accessible through the "API Keys" menu item.

It is also possible to access a "dummy" app for testing your API Client by using dummy_app_id as the username. When using dummy mode, no data is persisted to the database and no messages will be sent to users.

Examples

curl -s "https://api.intercom.io/v1/users" /
     -u dummy-app-id:dummy-api-key

Intercom.app_id = "dummy-app-id"
Intercom.api_key = "dummy-api-key"

Users

Getting all Users

GET https://api.intercom.io/v1/users

Retrieves a paginated list of all users in your application on Intercom.

Arguments

  • page: optional (defaults to 1)
  • per_page: optional (defaults to 500, max value of 500)
  • tag_id: optional — query for users that are tagged with a specific tag.
  • tag_name: optional — query for users that are tagged with a specific tag.

Response Structure

  • users: an array of User objects (same as returned by getting a single User)
  • total_count: the total number of Users tracked in your Intercom application
  • page: the current requested page
  • next_page: the next page number, if any
  • previous_page: the previous page number, if any
  • total_pages: the total number of pages

Example Request

curl -s "https://api.intercom.io/v1/users/?per_page=3" \
  -X GET \
  -u dummy-app-id:dummy-api-key

puts Intercom::User.all.count

Intercom::User.all.each do |user|
  puts user.email
end

Example Response

  "users": [
    {
      "email": "first.user@example.com",
      "user_id": "123",
      "name": "First User",
      "created_at": 1270000000,
      "last_impression_at": 1300000000,
      "custom_data": {
        "app_name": "Genesis",
        "monthly_spend": 155.5,
...
...
...
      "relationship_score": 90,
      "unsubscribed_from_emails": false
    }
  ],
  "total_count": 3,
  "page": 1,
  "next_page": null,
  "previous_page": null,
  "total_pages": 1
}
3
first.user@example.com
second.user@example.com
third.user@example.com

Getting a User

GET https://api.intercom.io/v1/users

Retrieves a user. Expects either the email or user_id you used to create the user.

Arguments

  • user_id: required (if no email)
  • email: required (if no user_id)

Example Request

curl -s "https://api.intercom.io/v1/users/?email=ben@intercom.io" \
  -X GET \
  -u dummy-app-id:dummy-api-key

user = Intercom::User.find(:email => "ben@intercom.io")

Example Response

{
  "email": "ben@intercom.io",
  "user_id": "123",
  "name": "Ben",
  "created_at": 1270000000,
  "last_impression_at": 1300000000,
  "custom_data": {
    "app_name": "Genesis",
    "monthly_spend": 155.5,
    "team_mates": 7
  },
  "social_profiles": [
    {
      "type": "twitter",
      "url": "http://twitter.com/abc",
      "username": "abc"
    },
    {
      "type": "facebook",
      "url": "http://facebook.com/vanity",
      "username": "vanity",
      "id": "13241141441141413"
    }
  ],
  "location_data": {
    "city_name": "Santiago",
    "continent_code": "SA",
    "country_name": "Chile",
    "latitude": -33.44999999999999,
    "longitude": -70.6667,
    "postal_code": "",
    "region_name": "12",
    "timezone": "Chile/Continental",
    "country_code": "CHL"
  },
  "session_count": 0,
  "last_seen_ip": "127.0.0.1",
  "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_3) AppleWebKit/535.11 (KHTML, like Gecko) Chrome/17.0.963.56 Safari/535.11",
  "relationship_score": 90,
  "unsubscribed_from_emails": false
}
#<Intercom::User:0x7fe80105f758
 @attributes = {
                     "email" => "ben@intercom.io",
                   "user_id" => "123",
                      "name" => "Ben",
                "created_at" => 1270000000,
        "last_impression_at" => 1300000000,
               "custom_data" => {
        "app_name" => "Genesis",
   "monthly_spend" => 155.5,
      "team_mates" => 7
  },
             "session_count" => 0,
              "last_seen_ip" => "127.0.0.1",
      "last_seen_user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_3) AppleWebKit/535.11 (KHTML, like Gecko) Chrome/17.0.963.56 Safari/535.11",
        "relationship_score" => 90,
  "unsubscribed_from_emails" => false
 },
 attr_accessor :location_data = {
       "city_name" => "Santiago",
  "continent_code" => "SA",
    "country_name" => "Chile",
        "latitude" => -33.44999999999999,
       "longitude" => -70.6667,
     "postal_code" => "",
     "region_name" => "12",
        "timezone" => "Chile/Continental",
    "country_code" => "CHL"
 },
 attr_accessor :social_profiles = [
  [0] #<Intercom::SocialProfile:0x7fe80105d598
   attr_reader :id = nil,
   attr_reader :type = "twitter",
   attr_reader :url = "http://twitter.com/abc",
   attr_reader :username = "abc"
  >,
  [1] #<Intercom::SocialProfile:0x7fe80105d340
   attr_reader :id = "13241141441141413",
   attr_reader :type = "facebook",
   attr_reader :url = "http://facebook.com/vanity",
   attr_reader :username = "vanity"
  >
 ]
>

Creating a User

POST https://api.intercom.io/v1/users

Creates a user. Expects a JSON object describing the user.

N.B. Social and geo location data is fetched asynchronously, so a secondary call to users will be required to fetch it.

Arguments

  • user_id: required (if no email) — a unique string identifier for the user
  • email: required (if no user_id) — the user's email address
  • name: The user's full name
  • created_at: A UNIX timestamp representing the date the user was created
  • custom_data: A hash of key/value pairs containing any other data about the user you want Intercom to store.
  • last_seen_ip: An ip address (e.g. "1.2.3.4") representing the last ip address the user visited your application from. (Used for updating location_data)
  • last_seen_user_agent: The user agent the user last visited your application with.
  • companies: An array of hashes describing the companies this user belongs to. Currently companies are not returned in the response.
  • last_request_at or last_impression_at: A UNIX timestamp representing the date the user last visited your application.

Example Request

curl -s "https://api.intercom.io/v1/users" \
  -X POST \
  -u dummy-app-id:dummy-api-key \
  -H "Content-Type: application/json" \
  --data '{
            "email" : "ben@intercom.io",
            "user_id" : "7902",
            "name" : "Ben McRedmond",
            "created_at" : 1257553080,
            "custom_data" : {"plan" : "pro"},
            "last_seen_ip" : "1.2.3.4",
            "last_seen_user_agent" : "ie6",
            "companies" : [
              {
                "id" : 6,
                "name" : "Intercom",
                "created_at" : 103201,
                "plan" : "Messaging",
                "monthly_spend" : 50
              }
            ],
            "last_request_at" : 1300000000
          }'

user = Intercom::User.create(:email => "ben@intercom.io",
                             :user_id => "7902",
                             :name => "Ben McRedmond",
                             :created_at => Time.now,
                             :custom_data => {"plan" => "pro"},
                             :last_seen_ip => "1.2.3.4",
                             :last_seen_user_agent => "ie6",
                             :last_request_at => Time.now)

Example Response

{
  "email": "ben@intercom.io",
  "user_id": "7902",
  "name": "Ben McRedmond",
  "created_at": 1257553080,
  "last_impression_at": 1300000000,
  "custom_data": {
    "plan": "pro"
  },
  "social_profiles": [
    {
      "type": "twitter",
      "url": "http://twitter.com/abc",
      "username": "abc"
    },
    {
      "type": "facebook",
      "url": "http://facebook.com/vanity",
      "username": "vanity",
      "id": "13241141441141413"
    }
  ],
  "location_data": {
    "city_name": "Santiago",
    "continent_code": "SA",
    "country_name": "Chile",
    "latitude": -33.44999999999999,
    "longitude": -70.6667,
    "postal_code": "",
    "region_name": "12",
    "timezone": "Chile/Continental",
    "country_code": "CHL"
  },
  "session_count": 0,
  "last_seen_ip": "1.2.3.4",
  "last_seen_user_agent": "ie6",
  "relationship_score": 90,
  "unsubscribed_from_emails": false
}
#<Intercom::User:0x7fef7b828d50
 @attributes = {
                     "email" => "ben@intercom.io",
                   "user_id" => "7902",
                      "name" => "Ben McRedmond",
                "created_at" => 1366697879,
               "custom_data" => {
   "plan" => "pro"
  },
              "last_seen_ip" => "1.2.3.4",
      "last_seen_user_agent" => "ie6",
           "last_request_at" => 1366697879,
        "last_impression_at" => 1366697879,
             "session_count" => 0,
        "relationship_score" => 90,
  "unsubscribed_from_emails" => false
 },
 attr_accessor :location_data = {
       "city_name" => "Santiago",
  "continent_code" => "SA",
    "country_name" => "Chile",
        "latitude" => -33.44999999999999,
       "longitude" => -70.6667,
     "postal_code" => "",
     "region_name" => "12",
        "timezone" => "Chile/Continental",
    "country_code" => "CHL"
 },
 attr_accessor :social_profiles = [
  [0] #<Intercom::SocialProfile:0x7fef7d009438
   attr_reader :id = nil,
   attr_reader :type = "twitter",
   attr_reader :url = "http://twitter.com/abc",
   attr_reader :username = "abc"
  >,
  [1] #<Intercom::SocialProfile:0x7fef7d009000
   attr_reader :id = "13241141441141413",
   attr_reader :type = "facebook",
   attr_reader :url = "http://facebook.com/vanity",
   attr_reader :username = "vanity"
  >
 ]
>

Updating a User

PUT https://api.intercom.io/v1/users

Updates a user. Expects a JSON object describing the user.

Arguments

  • user_id: required (if no email) — a unique string identifier for the user
  • email: required (if no user_id) — the user's email address
  • name: The user's full name
  • created_at: A UNIX timestamp representing the date the user was created
  • custom_data: A hash of key/value pairs containing any other data about the user you want Intercom to store.
  • last_seen_ip: The last ip address (e.g. "1.2.3.4") this user visited your application from. (Used for updating location_data)
  • last_seen_user_agent: The user agent the user last visited your application with.
  • companies: An array of hashes describing the companies this user belongs to. Currently companies are not returned in the response.
  • last_request_at or last_impression_at: A UNIX timestamp representing the date the user last visited your application.

Example Request

curl -s "https://api.intercom.io/v1/users" \
  -X PUT \
  -u dummy-app-id:dummy-api-key \
  -H "Content-Type: application/json" \
  --data '{
            "email" : "ben@intercom.io",
            "name" : "Benjamin McRedmond"
          }'

user = Intercom::User.find(:email => "ben@intercom.io")
user.name = "Benjamin McRedmond"
user.save

Example Response

{
  "email": "ben@intercom.io",
  "user_id": "123",
  "name": "Benjamin McRedmond",
  "created_at": 1270000000,
  "last_impression_at": 1300000000,
  "custom_data": {
    "app_name": "Genesis",
    "monthly_spend": 155.5,
    "team_mates": 7
  },
  "social_profiles": [
    {
      "type": "twitter",
      "url": "http://twitter.com/abc",
      "username": "abc"
    },
    {
      "type": "facebook",
      "url": "http://facebook.com/vanity",
      "username": "vanity",
      "id": "13241141441141413"
    }
  ],
  "location_data": {
    "city_name": "Santiago",
    "continent_code": "SA",
    "country_name": "Chile",
    "latitude": -33.44999999999999,
    "longitude": -70.6667,
    "postal_code": "",
    "region_name": "12",
    "timezone": "Chile/Continental",
    "country_code": "CHL"
  },
  "session_count": 0,
  "last_seen_ip": "127.0.0.1",
  "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_3) AppleWebKit/535.11 (KHTML, like Gecko) Chrome/17.0.963.56 Safari/535.11",
  "relationship_score": 90,
  "unsubscribed_from_emails": false
}
#<Intercom::User:0x7fb7b985ef30
 @attributes = {
                     "email" => "ben@intercom.io",
                   "user_id" => "123",
                      "name" => "Benjamin McRedmond",
                "created_at" => 1270000000,
        "last_impression_at" => 1300000000,
               "custom_data" => {
        "app_name" => "Genesis",
   "monthly_spend" => 155.5,
      "team_mates" => 7
  },
             "session_count" => 0,
              "last_seen_ip" => "127.0.0.1",
      "last_seen_user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_3) AppleWebKit/535.11 (KHTML, like Gecko) Chrome/17.0.963.56 Safari/535.11",
        "relationship_score" => 90,
  "unsubscribed_from_emails" => false
 },
 attr_accessor :location_data = {
       "city_name" => "Santiago",
  "continent_code" => "SA",
    "country_name" => "Chile",
        "latitude" => -33.44999999999999,
       "longitude" => -70.6667,
     "postal_code" => "",
     "region_name" => "12",
        "timezone" => "Chile/Continental",
    "country_code" => "CHL"
 },
 attr_accessor :social_profiles = [
  [0] #<Intercom::SocialProfile:0x7fb7ba05dad8
   attr_reader :id = nil,
   attr_reader :type = "twitter",
   attr_reader :url = "http://twitter.com/abc",
   attr_reader :username = "abc"
  >,
  [1] #<Intercom::SocialProfile:0x7fb7ba05d920
   attr_reader :id = "13241141441141413",
   attr_reader :type = "facebook",
   attr_reader :url = "http://facebook.com/vanity",
   attr_reader :username = "vanity"
  >
 ]
>

Deleting a User

DELETE https://api.intercom.io/v1/users

Deletes a user. Expects a JSON object with user_id or email to identify the user. Returns the deleted user on success. NOTE: All of a users conversations and message history will also be destroyed.

Arguments

  • user_id: required (if no email) — a unique string identifier for the user
  • email: required (if no user_id) — the user's email address

Example Request

curl -s "https://api.intercom.io/v1/users" \
  -X DELETE \
  -u dummy-app-id:dummy-api-key \
  -H "Content-Type: application/json" \
  --data '{
            "email" : "ben@intercom.io",
            "user_id" : "7902"
          }'

user = Intercom::User.delete(:email => "ben@intercom.io",
                             :user_id => "7902")

Example Response

{
  "email": "ben@intercom.io",
  "user_id": "7902",
  "name": "Ben McRedmond",
  "created_at": 1257553080,
  "last_impression_at": 1300000000,
  "custom_data": {
    "plan": "pro"
  },
  "social_profiles": [
    {
      "type": "twitter",
      "url": "http://twitter.com/abc",
      "username": "abc"
    },
    {
      "type": "facebook",
      "url": "http://facebook.com/vanity",
      "username": "vanity",
      "id": "13241141441141413"
    }
  ],
  "location_data": {
    "city_name": "Santiago",
    "continent_code": "SA",
    "country_name": "Chile",
    "latitude": -33.44999999999999,
    "longitude": -70.6667,
    "postal_code": "",
    "region_name": "12",
    "timezone": "Chile/Continental",
    "country_code": "CHL"
  },
  "session_count": 0,
  "last_seen_ip": "1.2.3.4",
  "last_seen_user_agent": "ie6",
  "relationship_score": 90,
  "unsubscribed_from_emails": false
}
#<Intercom::User:0x7fef7b828d50
 @attributes = {
                     "email" => "ben@intercom.io",
                   "user_id" => "7902",
                      "name" => "Ben McRedmond",
                "created_at" => 1366697879,
               "custom_data" => {
   "plan" => "pro"
  },
              "last_seen_ip" => "1.2.3.4",
      "last_seen_user_agent" => "ie6",
           "last_request_at" => 1366697879,
        "last_impression_at" => 1366697879,
             "session_count" => 0,
        "relationship_score" => 90,
  "unsubscribed_from_emails" => false
 },
 attr_accessor :location_data = {
       "city_name" => "Santiago",
  "continent_code" => "SA",
    "country_name" => "Chile",
        "latitude" => -33.44999999999999,
       "longitude" => -70.6667,
     "postal_code" => "",
     "region_name" => "12",
        "timezone" => "Chile/Continental",
    "country_code" => "CHL"
 },
 attr_accessor :social_profiles = [
  [0] #<Intercom::SocialProfile:0x7fef7d009438
   attr_reader :id = nil,
   attr_reader :type = "twitter",
   attr_reader :url = "http://twitter.com/abc",
   attr_reader :username = "abc"
  >,
  [1] #<Intercom::SocialProfile:0x7fef7d009000
   attr_reader :id = "13241141441141413",
   attr_reader :type = "facebook",
   attr_reader :url = "http://facebook.com/vanity",
   attr_reader :username = "vanity"
  >
 ]
>

Notes

Adds a note to a user of your application.

Creating a Note

POST https://api.intercom.io/v1/users/notes

Creates a note. Expects a JSON object describing the user and the note. Returns the newly created note in the response.

Arguments

  • user_id: required (if no email) — a unique identifier for the user
  • email: required (if no user_id) — the user's email address
  • body: required — the text of the note to add to the user

Example Request

curl -s "https://api.intercom.io/v1/users/notes" \
  -X POST \
  -u dummy-app-id:dummy-api-key \
  -H "Content-Type: application/json" \
  --data '{
            "email" : "ben@intercom.io",
            "body" : "This is the text of my note."
          }'

note = Intercom::Note.create(:email => "ben@intercom.io", :body => "This is the text of my note.")

Example Response

{
  "html": "<p>This is the text of my note.</p>",
  "created_at": null,
  "user": {
    "email": "somebody@example.com",
    "user_id": "123",
    "name": "Somebody",
    "created_at": 1270000000,
    "last_impression_at": 1300000000,
    "custom_data": {
      "app_name": "Genesis",
      "monthly_spend": 155.5,
      "team_mates": 7
    },
    "social_profiles": [
      {
        "type": "twitter",
        "url": "http://twitter.com/abc",
        "username": "abc"
      },
      {
        "type": "facebook",
        "url": "http://facebook.com/vanity",
        "username": "vanity",
        "id": "13241141441141413"
      }
    ],
    "location_data": {
      "city_name": "Santiago",
      "continent_code": "SA",
      "country_name": "Chile",
      "latitude": -33.44999999999999,
      "longitude": -70.6667,
      "postal_code": "",
      "region_name": "12",
      "timezone": "Chile/Continental",
      "country_code": "CHL"
    },
    "session_count": 0,
    "last_seen_ip": "127.0.0.1",
    "last_seen_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_3) AppleWebKit/535.11 (KHTML, like Gecko) Chrome/17.0.963.56 Safari/535.11",
    "relationship_score": 90,
    "unsubscribed_from_emails": false
  }
}
#<Intercom::Note:0x7f94ea02e8e8
 @attributes = {
       "email" => "ben@intercom.io",
        "body" => "This is the text of my note.",
        "html" => "<p>This is the text of my note.</p>",
  "created_at" => nil,
        "user" => {
                      "email" => "somebody@example.com",
                    "user_id" => "123",
                       "name" => "Somebody",
                 "created_at" => 1270000000,
         "last_impression_at" => 1300000000,
                "custom_data" => {
         "app_name" => "Genesis",
    "monthly_spend" => 155.5,
       "team_mates" => 7
   },
            "social_profiles" => [
    [0] {
         "type" => "twitter",
          "url" => "http://twitter.com/abc",
     "username" => "abc"
    },
    [1] {
         "type" => "facebook",
          "url" => "http://facebook.com/vanity",
     "username" => "vanity",
           "id" => "13241141441141413"
    }
   ],
              "location_data" => {
         "city_name" => "Santiago",
    "continent_code" => "SA",
      "country_name" => "Chile",
          "latitude" => -33.44999999999999,
         "longitude" => -70.6667,
       "postal_code" => "",
       "region_name" => "12",
          "timezone" => "Chile/Continental",
      "country_code" => "CHL"
   },
              "session_count" => 0,
               "last_seen_ip" => "127.0.0.1",
       "last_seen_user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_3) AppleWebKit/535.11 (KHTML, like Gecko) Chrome/17.0.963.56 Safari/535.11",
         "relationship_score" => 90,
   "unsubscribed_from_emails" => false
  }
 }
>

Tagging

View, create, and update tags. Optionally tag or untag a user with a given tag. Note, this doesn't work for segments as those are managed automatically based on filters.

Getting a tag

GET https://api.intercom.io/v1/tags

Get a tag by name. Expects a JSON object with the name of the tag. Returns the details of the tag.

Arguments

  • name: required — the name of the tag

Example Request

curl -s "https://api.intercom.io/v1/tags/?name=Free%20Trial" \
  -X GET \
  -u dummy-app-id:dummy-api-key

tag = Intercom::Tag.find(:name => "Free Trial")

Example Response

{
  "id": null,
  "name": "Free Trial",
  "color": "green",
  "segment": false,
  "tagged_user_count": null
}
#<Intercom::Tag:0x7fe1b385c2c0
 attr_accessor :color = "green",
 attr_accessor :name = "Free Trial",
 attr_reader :id = nil,
 attr_reader :segment = false,
 attr_reader :tagged_user_count = nil
>

Create a new tag

POST https://api.intercom.io/v1/tags

Create a new tag and, optionally, tag users. Expects a JSON object with an array of user identifiers and a tag name. Returns the details of the tag.

Arguments

  • user_ids: optional (create a tag without tagging any users) — an array of user_ids
  • emails: optional (create a tag without tagging any users) — an array of user emails
  • name: required — the name of the tag
  • tag_or_untag: required (if sending users to tag) — either "tag" or "untag", when creating only tag is supported
  • color: the color of the tag (must be "green", "red", "teal", "gold", "blue", or "purple")

Example Request

curl -s "https://api.intercom.io/v1/tags" \
  -X POST \
  -u dummy-app-id:dummy-api-key \
  -H "Content-Type: application/json" \
  --data '{
            "user_ids" : ["abc123", "def456"],
            "name" : "Free Trial",
            "tag_or_untag" : "tag"
          }'

tag = Intercom::Tag.create(:user_ids => ['abc123', 'def456'], :tag_or_untag => 'tag', :name => "Free Trial")

Example Response

{
  "id": null,
  "name": "Free Trial",
  "color": "green",
  "segment": false,
  "tagged_user_count": null
}
#<Intercom::Tag:0x7ff3d385d558
 attr_accessor :color = "green",
 attr_accessor :name = "Free Trial",
 attr_reader :id = nil,
 attr_reader :segment = false,
 attr_reader :tagged_user_count = nil
>

Update an already existing tag

PUT https://api.intercom.io/v1/tags

Update a tag and, optionally, tag or untag users. Expects a JSON object with an array of user identifiers and a tag name. Returns the details of the tag.

Arguments

  • user_ids: optional (update a tag without tagging/untagging any users) — an array of user_ids
  • emails: optional (update a tag without tagging/untagging any users) — an array of user emails
  • name: required — the name of the tag
  • tag_or_untag: required (if sending users to tag) — either "tag" or "untag"
  • color: the color of the tag (must be "green", "red", "teal", "gold", "blue", or "purple")

Example Request

curl -s "https://api.intercom.io/v1/tags" \
  -X PUT \
  -u dummy-app-id:dummy-api-key \
  -H "Content-Type: application/json" \
  --data '{
            "user_ids" : ["abc123", "def456"],
            "name" : "Free Trial",
            "tag_or_untag" : "tag"
          }'

tag = Intercom::Tag.find(:name => "Free Trial")
tag.user_ids = ["abc123"]
tag.color = "red"
tag.tag_or_untag = "tag"
tag.save

Example Response

{
  "id": null,
  "name": "Free Trial",
  "color": "green",
  "segment": false,
  "tagged_user_count": null
}
#<Intercom::Tag:0x7f8fd085c1b0
 attr_accessor :color = "red",
 attr_accessor :name = "Free Trial",
 attr_reader :id = nil,
 attr_reader :segment = false,
 attr_reader :tagged_user_count = nil,
 attr_writer :tag_or_untag = "tag",
 attr_writer :user_ids = [
  [0] "abc123"
 ]
>

Impressions

Impressions record a user visiting a page in your app, this should be called on every page the user visits.

Creating an Impression

POST https://api.intercom.io/v1/users/impressions

Creates an impression. Expects a JSON object describing the user. Will include an unread_messages counter in the response, which informs the client as to whether or not to fetch messages.

Arguments

  • user_id: required (if no email) — a unique identifier for the user
  • email: required (if no user_id) — the user's email address
  • user_ip: optional — ip address the user accessed from (Used for updating location_data)
  • user_agent: optional — The user agent the user last visited your application with
  • current_url: optional — The current url of the user

Example Request

curl -s "https://api.intercom.io/v1/users/impressions" \
  -X POST \
  -u dummy-app-id:dummy-api-key \
  -H "Content-Type: application/json" \
  --data '{
            "email" : "ben@intercom.io"
          }' 

impression = Intercom::Impression.create(:email => "ben@intercom.io", :user_agent => "my-awesome-android-app-v0.0.1")

Example Response

{
  "unread_messages": 1
}
#<Intercom::Impression:0x7faa7b0286e0
 @attributes = {
            "email" => "ben@intercom.io",
       "user_agent" => "my-awesome-android-app-v0.0.1",
  "unread_messages" => 1
 }
>

Message Threads

Getting Message Threads

GET https://api.intercom.io/v1/users/message_threads

Gets a user's message threads. Expects either the email or user_id you used to create the user. If a thread_id is specified only that thread will be returned.

When thread_id is omitted, we return the user entire inbox, including any newly matching auto messages. Use current_url to pick up newly matching auto messages that target a specific url.

Arguments

  • user_id: required (if no email) — a unique identifier for the user
  • email: required (if no user_id) — the user's email address
  • thread_id: A message thread id (gotten from either getting all messages or creating a message)
  • current_url: optional — Intercom allows you to target messages so that they are only picked up when a user visits a particular part of your app

Example Request

curl -s "https://api.intercom.io/v1/users/message_threads?email=ben@intercom.io" \
  -X GET \
  -u dummy-app-id:dummy-api-key \


message_threads = Intercom::MessageThread.find_all(:email => "ben@intercom.io")

Example Response

[
  {
    "created_at": 1366697898,
    "updated_at": 1366611498,
    "read": true,
    "created_by_user": true,
    "thread_id": 5591,
    "message_type": "inbox",
    "messages": [
      {
        "created_at": 1366697898,
        "url": null,
        "html": "<p>Hey Intercom, What is up?</p>\n\n<p></p>",
        "from": {
          "email": "ben@intercom.io",
          "user_id": "123",
          "name": "Ben",
          "is_admin": false,
          "avatar": {
          }
        }
      },
      {
        "created_at": 1366525098,
        "url": null,
        "html": "<p>Not much, you?\n</p>"
      },
      {
        "created_at": 1366611498,
        "url": null,
        "html": "<p>Not much either :(</p>\n\n<p></p>",
        "from": {
          "email": "ben@intercom.io",
          "user_id": "123",
          "name": "Ben",
          "is_admin": false,
          "avatar": {
          }
        }
      }
    ]
  }
]
[
 [0] #<Intercom::MessageThread:0x7ff7f40601f0
  @attributes = {
        "created_at" => 1366697899,
        "updated_at" => 1366611499,
              "read" => true,
   "created_by_user" => true,
         "thread_id" => 5591,
      "message_type" => "inbox",
          "messages" => [
    [0] {
     "created_at" => 1366697899,
            "url" => nil,
           "html" => "<p>Hey Intercom, What is up?</p>\n\n<p></p>",
           "from" => {
         "email" => "ben@intercom.io",
       "user_id" => "123",
          "name" => "Ben",
      "is_admin" => false,
        "avatar" => {}
     }
    },
    [1] {
     "created_at" => 1366525099,
            "url" => nil,
           "html" => "<p>Not much, you?\n</p>"
    },
    [2] {
     "created_at" => 1366611499,
            "url" => nil,
           "html" => "<p>Not much either :(</p>\n\n<p></p>",
           "from" => {
         "email" => "ben@intercom.io",
       "user_id" => "123",
          "name" => "Ben",
      "is_admin" => false,
        "avatar" => {}
     }
    }
   ]
  }
 >
]

Example Request with thread_id

curl -s "https://api.intercom.io/v1/users/message_threads?email=ben@intercom.io&thread_id=123" \
  -X GET \
  -u dummy-app-id:dummy-api-key \


message_thread = Intercom::MessageThread.find(:email => "ben@intercom.io", :thread_id => 123)

Example Response with thread_id

{
  "created_at": 1366697900,
  "updated_at": 1366611500,
  "read": true,
  "created_by_user": true,
  "thread_id": 5591,
  "message_type": "inbox",
  "messages": [
    {
      "created_at": 1366697900,
      "url": null,
      "html": "<p>Hey Intercom, What is up?</p>\n\n<p></p>",
      "from": {
        "email": "bob@example.com",
        "user_id": "456",
        "name": "Bob",
        "is_admin": false,
        "avatar": {
        }
      }
    },
    {
      "created_at": 1366525100,
      "url": null,
      "html": "<p>Not much, you?\n</p>"
    },
    {
      "created_at": 1366611500,
      "url": null,
      "html": "<p>Not much either :(</p>\n\n<p></p>",
      "from": {
        "email": "ben@intercom.io",
        "user_id": "123",
        "name": "Ben",
        "is_admin": false,
        "avatar": {
        }
      }
    }
  ]
}
#<Intercom::MessageThread:0x7f916285f340
 @attributes = {
       "created_at" => 1366697901,
       "updated_at" => 1366611501,
             "read" => true,
  "created_by_user" => true,
        "thread_id" => 5591,
     "message_type" => "inbox",
         "messages" => [
   [0] {
    "created_at" => 1366697901,
           "url" => nil,
          "html" => "<p>Hey Intercom, What is up?</p>\n\n<p></p>",
          "from" => {
        "email" => "bob@example.com",
      "user_id" => "456",
         "name" => "Bob",
     "is_admin" => false,
       "avatar" => {}
    }
   },
   [1] {
    "created_at" => 1366525101,
           "url" => nil,
          "html" => "<p>Not much, you?\n</p>"
   },
   [2] {
    "created_at" => 1366611501,
           "url" => nil,
          "html" => "<p>Not much either :(</p>\n\n<p></p>",
          "from" => {
        "email" => "ben@intercom.io",
      "user_id" => "123",
         "name" => "Ben",
     "is_admin" => false,
       "avatar" => {}
    }
   }
  ]
 }
>

Creating a Message Thread

POST https://api.intercom.io/v1/users/message_threads

Creates a message thread from a user to you. Expects either the email or user_id you used to create the user, and a body for the message.

N.B. We currently only support creating messages as if they were sent by the user to you, we do have future plans to support message creation from admins to users.

Arguments

  • user_id: required (if no email) — a unique identifier for the user
  • email: required (if no user_id) — the user's email address
  • body : required — the body of the message
  • url : the url the user was visiting when they sent the message

Example Request

curl -s "https://api.intercom.io/v1/users/message_threads" \
  -X POST \
  -u dummy-app-id:dummy-api-key \
  -H "Content-Type: application/json" \
  --data '{
            "email" : "ben@intercom.io",
            "body" : "Hey Intercom, What is up?",
            "url" : "http://example.com/my/sweet/url"
          }'


message_thread = Intercom::MessageThread.create(:email => "ben@intercom.io",
                                                :body => "Hey Intercom, What is up?",
                                                :url => "http://example.com/my/sweet/url")

Example Response

{
  "created_at": 1366697902,
  "updated_at": null,
  "read": true,
  "created_by_user": false,
  "thread_id": 5591,
  "message_type": "inbox",
  "messages": [
    {
      "created_at": 1366697902,
      "url": "http://example.com/my/sweet/url",
      "html": "<p>Hey Intercom, What is up?</p>",
      "from": {
        "email": "bob@example.com",
        "user_id": "456",
        "name": "Bob",
        "is_admin": false,
        "avatar": {
        }
      }
    }
  ]
}
#<Intercom::MessageThread:0x7fe91302e780
 @attributes = {
            "email" => "ben@intercom.io",
             "body" => "Hey Intercom, What is up?",
              "url" => "http://example.com/my/sweet/url",
       "created_at" => 1366697904,
       "updated_at" => nil,
             "read" => true,
  "created_by_user" => false,
        "thread_id" => 5591,
     "message_type" => "inbox",
         "messages" => [
   [0] {
    "created_at" => 1366697904,
           "url" => "http://example.com/my/sweet/url",
          "html" => "<p>Hey Intercom, What is up?</p>",
          "from" => {
        "email" => "bob@example.com",
      "user_id" => "456",
         "name" => "Bob",
     "is_admin" => false,
       "avatar" => {}
    }
   }
  ]
 }
>

Replying on a Message Thread

PUT https://api.intercom.io/v1/users/message_threads

Replies to a message thread from an admin from a user. Expects either the email or user_id you used to create the user, a message body and a thread_id. Optionally body can be ommitted and read sent instead, which is a boolean value marking the conversation as read or unread.

N.B. We currently only support creating messages as if they were sent by the user to you, we do have future plans to support message creation from admins to users.

Arguments

  • user_id: required (if no email) — a unique identifier for the user
  • email: required (if no user_id) — the user's email address
  • body : required (if no read) — the body of the message
  • read : required (if no body) — set a message as read or unread
  • url : the url the user was visiting when they sent the message
  • thread_id : required — the thread_id of the message

Example Request

curl -s "https://api.intercom.io/v1/users/message_threads" \
  -X PUT \
  -u dummy-app-id:dummy-api-key \
  -H "Content-Type: application/json" \
  --data '{
            "email" : "ben@intercom.io",
            "body" : "Not much either :(",
            "thread_id" : 11547,
            "url" : "http://example.com/my/sweet/url"
          }'

message_thread = Intercom::MessageThread.create(:email => "ben@intercom.io",
                                                :thread_id => 123,
                                                :body => "Not much either :(",
                                                :url => "http://example.com/my/sweet/url")

Example Response

{
  "created_at": 1366697904,
  "updated_at": 1366697905,
  "read": true,
  "created_by_user": true,
  "thread_id": 5591,
  "message_type": "inbox",
  "messages": [
    {
      "created_at": 1366697904,
      "url": null,
      "html": "<p>Hey Intercom, What is up?</p>\n\n<p></p>",
      "from": {
        "email": "bob@example.com",
        "user_id": "456",
        "name": "Bob",
        "is_admin": false,
        "avatar": {
        }
      }
    },
    {
      "created_at": 1366697905,
      "url": "http://example.com/my/sweet/url",
      "html": "<p>Not much either :(</p>",
      "from": {
        "email": "ben@intercom.io",
        "user_id": "123",
        "name": "Ben",
        "is_admin": false,
        "avatar": {
        }
      }
    }
  ]
}
#<Intercom::MessageThread:0x7fa641833f08
 @attributes = {
            "email" => "ben@intercom.io",
        "thread_id" => 5591,
             "body" => "Not much either :(",
              "url" => "http://example.com/my/sweet/url",
       "created_at" => 1366697906,
       "updated_at" => 1366697906,
             "read" => true,
  "created_by_user" => true,
     "message_type" => "inbox",
         "messages" => [
   [0] {
    "created_at" => 1366697906,
           "url" => nil,
          "html" => "<p>Hey Intercom, What is up?</p>\n\n<p></p>",
          "from" => {
        "email" => "bob@example.com",
      "user_id" => "456",
         "name" => "Bob",
     "is_admin" => false,
       "avatar" => {}
    }
   },
   [1] {
    "created_at" => 1366697906,
           "url" => "http://example.com/my/sweet/url",
          "html" => "<p>Not much either :(</p>",
          "from" => {
        "email" => "ben@intercom.io",
      "user_id" => "123",
         "name" => "Ben",
     "is_admin" => false,
       "avatar" => {}
    }
   }
  ]
 }
>