intercom-node
Official Node bindings to the Intercom API
Installation
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-client
This client is intended for server side use only. Please use the Intercom Javascript SDK for client-side operations.
Testing
npm test
Running the code locally
Compile using babel:
gulp babel
Require Intercom:
var Intercom = require('./dist/index');
Usage
Require Intercom:
var Intercom = require('intercom-client');
Create a client:
Using Access Tokens
var client = new Intercom.Client({ token: 'my_token' });
Callbacks
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});
Promises
This client library also supports using Promises instead of callbacks:
client.users.create({ email: 'foo@bar.com' }).then(function (r) { // ...});
Users
// Create a userclient.users.create({ email: 'jayne@serenity.io', custom_attributes: { foo: 'bar' }}, callback); // Update a userclient.users.update({ email: 'jayne@serenity.io', custom_attributes: { foo: 'bar' }}, callback);
// Create/update a user with custom attributesclient.users.create({ email: 'jayne@serenity.io', custom_attributes: { invited_friend: true } }, callback);
// List usersclient.users.list(callback);
// List users by tag or segmentclient.users.listBy({ tag_id: 'haven' }, callback);
// Scroll through users listclient.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 idclient.users.find({ id: '55b9eaf' }, callback); // Find user by user_idclient.users.find({ user_id: 'foobar' }, callback); // Find user by emailclient.users.find({ email: 'jayne@serenity.io' }, callback);
// Delete user by idclient.users.delete({ id: '1234' }, callback);
Leads
// Create a contactclient.leads.create(function (r) { console.log(r);}); // Create a contact with attributesclient.leads.create({ email: 'jayne@serenity.io' }, function (r) { console.log(r);});
// Update a contact by idclient.leads.update({ id: '5435345', email: 'wash@serenity.io' }, callback);
// List contactsclient.leads.list(callback);
// Scroll through contacts listclient.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 emailclient.leads.listBy({ email: 'wash@serenity.io' }, callback);
// Find contact by idclient.leads.find({ id: '5342423' }, callback);
// Delete contact by idclient.leads.delete({ id: '5342423' }, callback);
// Convert Leads into Usersvar conversion = { contact: { user_id: '1234-5678-9876' }, user: { email: 'mal@serenity.io' }};client.leads.convert(conversion, callback);
Visitors
// Update a visitor by idclient.visitors.update({ id: '5435345', email: 'wash@serenity.io' }, callback);
// Find visitor by id or user_idclient.visitors.find({ id: '5342423' }, callback);client.visitors.find({ user_id: '5b868511-ca3b-4eac-8d26-cfd82a83ac76' }, callback);
// Delete visitor by idclient.visitors.delete({ id: '5342423' }, callback);
// Convert visitors into Usersvar conversion = { visitor: { user_id: '1234-5678-9876' }, user: { email: 'mal@serenity.io' }, type: "user"};client.visitors.convert(conversion, callback);
// Convert visitors into Leadvar conversion = { visitor: { user_id: '1234-5678-9876' }, type: "lead"};client.visitors.convert(conversion, callback);
Companies
// Create/update a companyclient.companies.create({ company_id: '1234', name: 'serenity' }, function (r) { console.log(r);});
// List companiesclient.companies.list(callback);
// List companies by tag or segmentclient.companies.listBy({ tag_id: 'haven' }, callback);
// Scroll through companies listclient.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 idclient.companies.find({ id: '1234' }, callback);
// List company users by id or company_idclient.companies.listUsers({ id: '1234' }, callback);client.companies.listUsers({ company_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 a eventclient.events.create({ event_name: 'Foo', created_at: 1439826340, user_id: 'bar', metadata: { type: 'baz' }}, function (d) { console.log(d);});
// List events by userclient.events.listBy({ type: 'user', user_id: 'bar'}, callback);
Counts
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);
Admins
// List adminsclient.admins.list(callback);
// Find current admin (only works with OAuth tokens)client.admins.me(callback);
Tags
// Create a tagclient.tags.create({ name: 'haven' }, callback);
// Tag a user by idclient.tags.tag({ name: 'haven', users: [{ id: '54645654' }] }, callback);
// Tag a company by idclient.tags.tag({ name: 'haven', companies: [{ id: '54645654' }] }, callback);
// Untag a user by idclient.tags.untag({ name: 'haven', users: [{ id: '5345342' }] }, callback);
// List tagsclient.tags.list(callback);
// Delete a tag by idclient.tags.delete({ id: '130963' }, callback);
Segments
// List segmentsclient.segments.list(callback);
// Find segment by idclient.segments.find({ id: '55719a4a' }, callback);
Messages
// Admin initiated messages:// Sending an email to a Uservar 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 conversations (documentation):
client.conversations.list({ type: 'admin', admin_id: 21599 }, callback);
// Fetch a conversationclient.conversations.find({ id: '1062682196' }, callback);
// Reply to a conversationvar 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 attachmentsvar 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 readclient.conversations.markAsRead({ id: '1039067180' }, callback);
Notes
// Create a notevar note = { admin_id: 21599, body: 'Hello notes!', user: { id: '55b26822ce97179e52001334' }}; client.notes.create(note, callback);
// List notes by userclient.notes.list({ email: 'bob@intercom.io' }, callback);
//Fetch a noteclient.notes.find({ id: '3342887' }, callback);
Pagination
When listing, the Intercom API may return a pagination object:
You can grab the next page of results using the client:
client.nextPage(response.pages, callback);
Identity verification
intercom-node
provides a helper for using identity verification:
import { IdentityVerification } from 'intercom-client';IdentityVerification.userHash({secretKey: 's3cre7', identifier: 'jayne@serenity.io'});
License
Apache-2.0
Pull Requests
-
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.