Official Node bindings to the Intercom API
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)
npm install intercom-clientThis client is intended for server side use only. Please use the Intercom Javascript SDK for client-side operations.
npm testCompile using babel:
gulp babelRequire Intercom:
var Intercom = require('./dist/index');Require Intercom:
var Intercom = require('intercom-client');Create a client:
var client = new Intercom.Client({ token: 'my_token' });This client library supports two kinds of 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
});This client library also supports using Promises instead of callbacks:
client.users.create({ email: '[email protected]' }).then(function (r) {
// ...
});// 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);// List users
client.users.list(callback);// List users by tag or segment
client.users.listBy({ tag_id: 'haven' }, callback);// Scroll through users list
client.users.scroll.each({}, function(res) {
// if you return a promise from your callback, the client will only scroll
// after this promise has resolved
new Bluebird((resolve) => {
setTimeout(() => {
console.log(res.body.users.length);
// Your custom logic
resolve();
}, 500)
})
});// Find user by id
client.users.find({ id: '55b9eaf' }, callback);
// Find user by user_id
client.users.find({ user_id: 'foobar' }, callback);
// Find user by email
client.users.find({ email: '[email protected]' }, callback);// Archive user by id (https://developers.intercom.com/v2.0/reference#archive-a-user)
client.users.archive({ id: '1234' }, callback);// Permanently delete a user user by id (https://developers.intercom.com/v2.0/reference#delete-users)
const intercomUserId = '123'
client.users.requestPermanentDeletion(intercomUserId, callback);// 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);// List contacts
client.leads.list(callback);// Scroll through contacts list
client.leads.scroll.each({}, function(res) {
// if you return a promise from your callback, the client will only scroll
// after this promise has resolved
new Bluebird((resolve) => {
setTimeout(() => {
console.log(res.body.users.length);
// Your custom logic
resolve();
}, 500)
})
});// List contacts by email
client.leads.listBy({ email: '[email protected]' }, callback);// Find contact by id
client.leads.find({ id: '5342423' }, callback);// Delete contact by id
client.leads.delete({ id: '5342423' }, callback);// Convert Leads into Users
var conversion = {
contact: { user_id: '1234-5678-9876' },
user: { email: '[email protected]' }
};
client.leads.convert(conversion, callback);// Update a visitor by id
client.visitors.update({ id: '5435345', email: '[email protected]' }, callback);// Find visitor by id or user_id
client.visitors.find({ id: '5342423' }, callback);
client.visitors.find({ user_id: '5b868511-ca3b-4eac-8d26-cfd82a83ac76' }, callback);// Delete visitor by id
client.visitors.delete({ id: '5342423' }, callback);// 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 Lead
var conversion = {
visitor: { user_id: '1234-5678-9876' },
type: "lead"
};
client.visitors.convert(conversion, callback);// Create/update a company
client.companies.create({ company_id: '1234', name: 'serenity' }, function (r) {
console.log(r);
});// List companies
client.companies.list(callback);// List companies by tag or segment
client.companies.listBy({ tag_id: 'haven' }, callback);// Scroll through companies list
client.companies.scroll.each({}, function(res) {
// if you return a promise from your callback, the client will only scroll
// after this promise has resolved
new Bluebird((resolve) => {
setTimeout(() => {
console.log(res.body.companies.length);
// Your custom logic
resolve();
}, 500)
})
});// Find company by id
client.companies.find({ id: '1234' }, callback);// List company users by id or company_id
client.companies.listUsers({ id: '1234' }, callback);
client.companies.listUsers({ company_id: '1234' }, callback);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 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
client.events.listBy({
type: 'user',
user_id: 'bar'
}, callback);client.counts.appCounts(callback);
client.counts.conversationCounts(callback);
client.counts.conversationAdminCounts(callback);
client.counts.userTagCounts(callback);
client.counts.userSegmentCounts(callback);
client.counts.companyTagCounts(callback);
client.counts.companySegmentCounts(callback);
client.counts.companyUserCounts(callback);// List admins
client.admins.list(callback);// Find current admin (only works with OAuth tokens)
client.admins.me(callback);// Find admin by ID
client.admins.find('123456789', callback);
// Create a tag
client.tags.create({ name: 'haven' }, callback);// 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);// Delete a tag by id
client.tags.delete({ id: '130963' }, callback);// List segments
client.segments.list(callback);// Find segment by id
client.segments.find({ id: '55719a4a' }, callback);// Admin initiated 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);Listing conversations (documentation):
client.conversations.list({ type: 'admin', admin_id: 21599 }, callback);// Fetch a 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);// Assign a conversation to an admin
var assignment = {
id: '13879167940',
type: 'admin',
admin_id: '1309092',
assignee_id: '1723471',
message_type: 'assignment'
};
client.conversations.reply(assignment, callback);
// Assign a conversation to unassigned
var assignment = {
id: '13879167940',
type: 'admin',
admin_id: '1309092',
assignee_id: '0',
message_type: 'assignment'
}
client.conversations.reply(assignment, callback);// Mark a conversation as read
client.conversations.markAsRead({ id: '1039067180' }, callback);// 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);//Fetch a note
client.notes.find({ id: '3342887' }, callback);When listing, the Intercom API may return a pagination object:
{
"pages": {
"next": "..."
}
}You can grab the next page of results using the client:
client.nextPage(response.pages, callback);intercom-node provides a helper for using identity verification:
import { IdentityVerification } from 'intercom-client';
IdentityVerification.userHash({secretKey: 's3cre7', identifier: '[email protected]'});Apache-2.0
-
Add tests! Your patch won't be accepted if it doesn't have tests.
-
Document any change in behaviour. Make sure the README and any other relevant documentation are kept up-to-date.
-
Create topic branches. Don't ask us to pull from your master branch.
-
One pull request per feature. If you want to do more than one thing, send multiple pull requests.
-
Send coherent history. Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please squash them before sending them to us.