intercom-client

What is intercom-client?

The intercom-client npm package is a Node.js client for the Intercom API. It allows developers to interact with Intercom's services programmatically, enabling functionalities such as managing users, sending messages, and handling conversations.

What are intercom-client's main functionalities?

Managing Users

This feature allows you to create and manage users in your Intercom account. The code sample demonstrates how to create a new user with an email and name.

const Intercom = require('intercom-client');
const client = new Intercom.Client({ token: 'your_access_token' });

client.users.create({
  email: '[e-mail]',
  name: 'Test User'
}).then(response => {
  console.log(response.body);
}).catch(error => {
  console.error(error);
});

Sending Messages

This feature allows you to send messages to users. The code sample demonstrates how to send an in-app message from an admin to a user.

const Intercom = require('intercom-client');
const client = new Intercom.Client({ token: 'your_access_token' });

client.messages.create({
  message_type: 'inapp',
  body: 'Hello, this is a test message!',
  from: {
    type: 'admin',
    id: 'admin_id'
  },
  to: {
    type: 'user',
    id: 'user_id'
  }
}).then(response => {
  console.log(response.body);
}).catch(error => {
  console.error(error);
});

Handling Conversations

This feature allows you to list and manage conversations. The code sample demonstrates how to list all conversations for a specific admin.

const Intercom = require('intercom-client');
const client = new Intercom.Client({ token: 'your_access_token' });

client.conversations.list({
  type: 'admin',
  admin_id: 'admin_id'
}).then(response => {
  console.log(response.body);
}).catch(error => {
  console.error(error);
});

Other packages similar to intercom-client

hubspot-api

The hubspot-api package provides a client for interacting with HubSpot's API. Similar to intercom-client, it allows for managing contacts, sending messages, and handling conversations. However, it is specific to HubSpot's CRM and marketing tools.

zendesk-node-api

The zendesk-node-api package is a client for the Zendesk API. It offers functionalities for managing tickets, users, and other support-related tasks. While it shares some similarities with intercom-client in terms of user and conversation management, it is tailored for Zendesk's customer support platform.

freshdesk-api

The freshdesk-api package provides a client for interacting with Freshdesk's API. It allows for managing tickets, contacts, and conversations, similar to intercom-client. However, it is designed specifically for Freshdesk's customer support and helpdesk services.

README

intercom-node

Official Node bindings to the Intercom API

Project Updates

Maintenance

We're currently building a new team to provide in-depth and dedicated SDK support.

In the meantime, we'll be operating on limited capacity, meaning all pull requests will be evaluated on a best effort basis and will be limited to critical issues.

We'll communicate all relevant updates as we build this new team and support strategy in the coming months.

Installation

yarn add intercom-client

This client is intended for server side use only. Please use the Intercom Javascript SDK for client-side operations.

Testing

yarn test

Running the code locally

Compile using babel:

yarn 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: '[e-mail]' }).then(function (r) {
  // ...
});

Request Options

This client library also supports passing in request options:

var client = new Intercom.Client({ token: 'my_token' });
client.useRequestOpts({
  baseUrl: 'http://local.test-server.com',
  // Uses the forever-agent / http(s).Agent({keepAlive:true})
  forever: true
});

Note that certain request options (such as json, and certain headers names cannot be overriden).

Setting the API version

We version our API (see the "Choose Version" section of the API & Webhooks Reference for details). You can specify which version of the API to use when performing API requests using request options:

var client = new Intercom.Client({ token: 'my_token' });
client.useRequestOpts({
  headers: {
    'Intercom-Version': 1.2
  }
});

Users

// Create a user
client.users.create({
  email: '[e-mail]',
  custom_attributes: {
    foo: 'bar'
  }
}, callback);

// Update a user
client.users.update({
  email: '[e-mail]',
  custom_attributes: {
    foo: 'bar'
  }
}, callback);

// Create/update a user with custom attributes
client.users.create({ email: '[e-mail]', 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: '[e-mail]' }, callback);

// Archive user by id (https://developers.intercom.com/intercom-api-reference/reference#archive-a-user)
client.users.archive({ id: '1234' }, callback);

// Permanently delete a user by id (https://developers.intercom.com/intercom-api-reference/reference#delete-users)
const intercomUserId = '123'
client.users.requestPermanentDeletion(intercomUserId, callback);

// Permanently delete a user by id in params
client.users.requestPermanentDeletionByParams({ id: '55b9eaf' }, callback);

// Permanently delete a user by user_id
client.users.requestPermanentDeletionByParams({ user_id: 'foobar' }, callback);

// Permanently delete a user by email
client.users.requestPermanentDeletionByParams({ email: '[e-mail]' }, callback);

Leads

// Create a contact
client.leads.create(function (r) {
  console.log(r);
});

// Create a contact with attributes
client.leads.create({ email: '[e-mail]' }, function (r) {
  console.log(r);
});

// Update a contact by id
client.leads.update({ id: '5435345', email: '[e-mail]' }, 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.contacts.length);
      // Your custom logic
      resolve();
   }, 500)
 })
});

// List contacts by email
client.leads.listBy({ email: '[e-mail]' }, 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: '[e-mail]' }
};
client.leads.convert(conversion, callback);

Customers

// Search for customers
client.customers.search({
  query: { field: 'name', operator: '=', name: 'Alice'},
  sort: { field: 'name', order: 'ascending'},
  pagination: { per_page: 10 }
}, callback);

Visitors

// Update a visitor by id
client.visitors.update({ id: '5435345', email: '[e-mail]' }, 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: '[e-mail]' },
  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);

Companies

// 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);

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 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);

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 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);

// Update admin away mode and reassign settings
client.admins.away('123456789', {'away_mode_enabled': true, 'away_mode_reassign': false}, callback);

Tags

// 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);

Segments

// List segments
client.segments.list(callback);

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

Messages

// 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);

Conversations

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);

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: '[e-mail]' }, callback);

//Fetch a note
client.notes.find({ id: '3342887' }, callback);

Pagination

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);

Identity verification

intercom-node provides a helper for using identity verification:

import { IdentityVerification } from 'intercom-client';

IdentityVerification.userHash({secretKey: 's3cre7', identifier: '[e-mail]'});

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.