Intercom Node SDK

Official Node bindings to the Intercom API

📘

Docker for Intercom Node

Try out our Docker Image (Beta) to help you get started more quickly.
It should make it easier to get setup with the SDK and start interacting with the API.
(Note, this is in Beta and is for testing purposes only, it should not be used in production)

📘

Installation and Configuration Steps

For information on how to install and configure the Intercom Node SDK please see the intercom-node github page. For general code examples please see below.

Creating a Client

Require Intercom

//Require Intercom
var Intercom = require('intercom-client');

// Or with an OAuth or Access token:
var client = new Intercom.Client({ token: 'my_token' });

Callbacks and Promises

Callbacks

client.users.list(function (d) {
  // d is the response from the server
});
// Or
client.users.list(function (err, d) {
  // err is an error response object, or null
  // d is a successful response object, or null
});

Promises

//This client library also supports using Promises instead of callbacks:
```node
client.users.create({ email: '[email protected]' }).then(function (r) {
  // ...
});
```

Users

Create/update/delete users

Create a user

client.users.create({
  email: '[email protected]',
  custom_attributes: {
    foo: 'bar'
  }
}, callback);

Update a user

client.users.update({
  email: '[email protected]',
  custom_attributes: {
    foo: 'bar'
  }
}, callback);

Create/update a user with custom attributes

client.users.create({ email: '[email protected]', custom_attributes: { invited_friend: true } }, callback);

Delete user by id

client.users.delete({ id: '1234' }, callback);

List users

List users

client.users.list(callback);

List users by tag or segment

client.users.listBy({ tag_id: 'haven' }, callback);

Add user to company

client.users.update({
  email: '[email protected]',
  company: { 
    company_id: '001'
  }
}, function(response) { console.log(response.status); });

Find users

Find user by user_id

client.users.find({ user_id: 'foobar' }, callback);

Find user by email

client.users.find({ email: '[email protected]' }, callback);

Find user by id

client.users.find({ id: '55b9eaf' }, callback);

Delete user by ID

client.users.delete({ id: '1234' }, callback);

Leads

Create/update/delete contacts

Create a contact

client.leads.create(function (r) {
  console.log(r);
});

Create a contact with attributes

client.leads.create({ email: '[email protected]' }, function (r) {
  console.log(r);
});

Update a contact by id

client.leads.update({ id: '5435345', email: '[email protected]' }, callback);

Delete a contact

client.leads.delete({ id: '5342423' }, callback);

List/find contacts

List contacts

client.leads.list(callback);

List contacts by email

client.leads.listBy({ email: '[email protected]' }, callback);

Find contact by id

client.leads.find({ id: '5342423' }, callback);

Convert leads into users

Convert Leads into Users

var conversion = {
  contact: { user_id: '1234-5678-9876' },
  user: { email: '[email protected]' }
};
client.leads.convert(conversion, callback);

Visitors

Find/update/delete visitors

Find visitor by id or user_id

client.visitors.find({ id: '5342423' }, callback);
//or by user_id
client.visitors.find({ user_id: '5b868511-ca3b-4eac-8d26-cfd82a83ac76' }, callback);

Update a visitor by id

client.visitors.update({ id: '5435345', email: '[email protected]' }, callback);

Delete visitor by id

client.visitors.delete({ id: '5342423' }, callback);

Convert visitors into users or leads

Convert visitors into Users

var conversion = {
  visitor: { user_id: '1234-5678-9876' },
  user: { email: '[email protected]' },
  type: "user"
};
client.visitors.convert(conversion, callback);

Convert visitors into Leads

var conversion = {
  visitor: { user_id: '1234-5678-9876' },
  type: "lead"
};
client.visitors.convert(conversion, callback);

Companies

Create/update companies

Create/update a company

client.companies.create({ company_id: '1234', name: 'serenity' }, function (r) {
  console.log(r);
});

List and find companies

List companies

client.companies.list(callback);

List companies by tag or segment

client.companies.listBy({ tag_id: 'haven' }, callback);

Find company by id

client.companies.find({ id: '1234' }, callback);

List company users

client.companies.listUsers({ id: '1234' }, callback);

Events

📘

Note: events will work when identified by 'email'. The event_name and created_at params are both required. Either user_id OR email is required

Create and list events

Create a event

client.events.create({
  event_name: 'Foo',
  created_at: 1439826340,
  user_id: 'bar',
  metadata: { type: 'baz' }
}, function (d) {
  console.log(d);
});

List events by user

// List events by user
client.events.listBy({
    type: 'user',
    user_id: 'bar'
}, callback);

Counts

Counts available

List of available counts

//Global count
client.counts.appCounts(callback);
//Conversation counts
client.counts.conversationCounts(callback);
//Admin conversation counts
client.counts.conversationAdminCounts(callback);
//Tag counts
client.counts.userTagCounts(callback);
//User segment counts
client.counts.userSegmentCounts(callback);
//Company tag counts
client.counts.companyTagCounts(callback);
//Company segment counts
client.counts.companySegmentCounts(callback);
//Company user counts
client.counts.companyUserCounts(callback);

Admins

List and find admins

List admins

client.admins.list(callback);

Find current admin

// Find current admin only works with OAuth tokens
client.admins.me(callback);

Tags

Create, delete tags

Create a tag

client.tags.create({ name: 'haven' }, callback);

Delete a tag by id

client.tags.delete({ id: '130963' }, callback);

Apply, remove and list tags

Tag a user by id

client.tags.tag({ name: 'haven', users: [{ id: '54645654' }] }, callback);

Tag a company by id

client.tags.tag({ name: 'haven', companies: [{ id: '54645654' }] }, callback);

Untag a user by id

client.tags.untag({ name: 'haven', users: [{ id: '5345342' }] }, callback);

List tags

client.tags.list(callback);

Segments

List and find segments

List segments

client.segments.list(callback);

Find segment by id

client.segments.find({ id: '55719a4a' }, callback);

Messages

Create admin or user initiated messages

Admin initiated email messages

// Sending an email to a User
var message = {
  message_type: "email",
  subject: "Hey",
  body: "Ponies, cute small horses or something more sinister?",
  template: "plain",
  from: {
    type: "admin",
    id: "21599"
  },
  to: {
    type: "user",
    id: "55c1ce1def857c31f80001af"
  }
}
client.messages.create(message, callback);

Creating a user-initiated message

var message = {
  from: {
    type: "user",
    id: "55c1ce1def857c31f80001af"
  },
  body: "Howdy"
}
client.messages.create(message, callback);

Conversations

Listing, finding, replying and changing the state of conversations

List conversations for admin

client.conversations.list({ type: 'admin', admin_id: 21599 }, callback);

Find a specific conversation

client.conversations.find({ id: '1062682196' }, callback);

Reply to a conversation

var reply = {
  id: '1039067180',
  intercom_user_id: '55b26822ce97179e52001334',
  body: 'Some reply :)',
  type: 'user',
  message_type: 'comment'
};
client.conversations.reply(reply, callback);

Reply to a conversation with attachments

var reply = {
  id: '1039067180',
  intercom_user_id: '55b26822ce97179e52001334',
  body: 'Some reply :)',
  type: 'user',
  message_type: 'comment',
  attachment_urls: ['http://www.example.com/myattachment.jpg']
};
client.conversations.reply(reply, callback);

Mark a conversation as read

client.conversations.markAsRead({ id: '1039067180' }, callback);

Notes

Create, list and find notes

Create a note

var note = {
  admin_id: 21599,
  body: 'Hello notes!',
  user: {
    id: '55b26822ce97179e52001334'
  }
};
client.notes.create(note, callback);

List notes by user

client.notes.list({ email: '[email protected]' }, callback);

Find a note

client.notes.find({ id: '3342887' }, callback);

Pagination

📘

When listing, the Intercom API may return a pagination object:

Pagination Object

{
  "pages": {
    "next": "..."
  }
}

Get next page

client.nextPage(response.pages, callback);

Secure mode

intercom-node provides a helper for using Secure Mode:

Using secure mode

import {SecureMode} from 'intercom-client';
SecureMode.userHash({secretKey: 's3cre7', identifier: '[email protected]'});

License

Apache-2.0