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

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

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 by calling usePromises on the client object:

let client = new Client('foo', 'bar').usePromises();
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);
});

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

Contacts

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

// Update a contact by id
client.contacts.update({ id: '5435345', email: '[e-mail]' }, callback);

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

// List contacts by email
client.contacts.listBy({ email: '[e-mail]' }, callback);

// Find contact by id
client.contacts.find({ id: '5342423' }, callback);

// Delete contact by id
client.contacts.delete({ id: '5342423' }, callback);

// Convert Contacts into Users
var conversion = {
  contact: { user_id: '1234-5678-9876' },
  user: { email: '[e-mail]' }
};
client.contacts.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

// Create a event
client.events.create({
  event_name: 'Foo',
  created_at: 1439826340,
  user_id: 'bar'
}, 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);

// 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:

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

License

Apache-2.0