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

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

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:

var client = new Intercom.Client('app_id', 'app_api_key');

// Or

var client = new Intercom.Client({ appId: 'app_id', appApiKey: 'app_api_key' });

// Or with an OAuth token:

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) {
  // ...
});

Users

// Create/update a user
client.users.create({ email: '[e-mail]' }, function (r) {
  console.log(r);
});

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

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

// List users by tag or segment
client.users.listBy({ tag_id: 'haven' }, callback);

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

// Delete user by id
client.users.delete({ id: '1234' }, 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);

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

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

// 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 a event
client.events.create({
  event_name: 'Foo',
  created_at: 1439826340,
  user_id: 'bar',
  metadata: { type: 'baz' }
}, function (d) {
  console.log(d);
});

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

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

Bulk users

The Bulk APIs allow for the asynchronous creation and deletion of users:

client.users.bulk([
  { create: { email: '[e-mail]' }},
  { create: { email: '[e-mail]'}}
], callback);

Bulk events

var event = {
  event_name: 'foo',
  created: 1438944979,
  email: '[e-mail]',
  metadata: { bar: 'baz' }
};

client.events.bulk([{ create: event }], 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);

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

Secure mode

intercom-node provides a helper for using Secure Mode:

import {SecureMode} from 'intercom-client';

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

License

Apache-2.0