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

Breaking changes

The Node SDK has been updated to support latest API version (2.6). The update also contains requested features, such like Typescript support. You can find more information on how-to migrate and what has changed in the migration guide.

Installation

yarn add intercom-client

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

Usage

Import Intercom:

import { Client } from 'intercom-client';

Create a client using access tokens:

const client = new Client({ tokenAuth: { token: 'my_token' } });

Request Options

This client library also supports passing in request options:

const client = new Client({ tokenAuth: { token: 'my_token' } });
client.useRequestOpts({
    baseURL: 'http://local.test-server.com',
});

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:

const client = new Client({ tokenAuth: { token: 'my_token' } });
client.useRequestOpts({
    headers: {
        'Intercom-Version': 2.6,
    },
});

Setting the API base url

If you are using the european instance of intercom and would like to call it directly and not be redirected through our US instance, you can set the baseUrl as follows:

const client = new Client({ tokenAuth: { token: 'my_token' } });
client.useRequestOpts({
    baseURL: 'https://api.eu.intercom.io',
});

Examples

Admins

Retrieve admin

const admin = await client.admins.find({ id: '123' });

Set Admin away

await client.admins.away({
    adminId: '123',
    enableAwayMode: true,
    enableReassignMode: false,
});

List all activity logs

await client.admins.listAllActivityLogs({
    before: new Date('Fri, 17 Dec 2021 18:02:18 GMT');,
    after: new Date('Fri, 17 Dec 2021 18:02:18 GMT');,
});

List all admins

const admins = await client.admins.list();

Articles

Create an article

const article = await client.articles.create({
    title: 'Thanks for everything',
    description: 'English description',
    body: '<p>This is the body in html</p>',
    authorId: 1,
    state: 'published',
    parentId: 1,
    parentType: 'collection',
    translatedContent: {
        fr: {
            title: 'Allez les verts',
            description: 'French description',
            body: '<p>French body in html</p>',
            author_id: 1,
            state: 'published',
        },
    },
});

Retrieve an article

const response = await client.articles.find({ id: '123' });

Update an article

const article = await client.articles.update({
    id: '123',
    title: 'Thanks for everything',
    description: 'English description',
    body: '<p>This is the body in html</p>',
    authorId: 1,
    state: 'published',
    parentId: 1,
    parentType: 'collection',
    translatedContent: {
        fr: {
            title: 'Allez les verts',
            description: 'French description',
            body: '<p>French body in html</p>',
            author_id: 1,
            state: 'published',
        },
    },
});

Delete an article

await client.articles.delete({ id: '123' });

List all articles

const response = await client.articles.list({
    page: 3,
    perPage: 12,
});

Companies

Create a company

const company = await client.companies.create({
    createdAt: dateToUnixTimestamp(new Date()),
    companyId: '46029',
    name: 'BestCompanyInc.',
    monthlySpend: 9001,
    plan: '1. Get pizzaid',
    size: 62049,
    website: 'http://the-best.one',
    industry: 'The Best One',
    customAttributes: {},
});

Update a company

const company = await client.companies.update({
    createdAt: dateToUnixTimestamp(new Date()),
    companyId: '46029',
    name: 'BestCompanyInc.',
    monthlySpend: 9001,
    plan: '1. Get pizzaid',
    size: 62049,
    website: 'http://the-best.one',
    industry: 'The Best One',
    customAttributes: {},
});

Retrieve a company

By id

const company = await client.companies.find({
    companyId: 123,
});

By name

const company = await client.companies.find({
    name: 'bruh moment inc.',
});

Delete a company

const company = await client.companies.delete({
    id: 62049,
});

List all companies

With pagination

const companies = await client.companies.list({
    page: 1,
    perPage: 35,
    order: Order.DESC,
});

With TagId and SegmentId

const companies = await client.companies.list({
    tagId: '1234',
    segmentId: '4567',
});

Scroll over companies

Using infinite scroll

const companies = await client.companies.scroll.each({});

Using manual scroll

const companies = await client.companies.scroll.next({
    scrollParam: '123_soleil',
});

Attach a contact

const response = await client.companies.attachContact({
    contactId: '123',
    companyId: '234',
});

Detach a contact

const response = await client.companies.detachContact({
    contactId: '123',
    companyId: '234',
});

List attached contacts

const response = await client.companies.listAttachedContacts({
    companyId: '123',
    page: 1,
    perPage: 15,
});

List attached segments

const response = await client.companies.listAttachedSegments({
    companyId: '123',
});

Contacts

Create Contact

With User Role

const user = await client.contacts.createUser({
    externalId: '536e564f316c83104c000020',
    phone: '[phone]',
    name: 'Niko Bellic',
    avatar: 'https://nico-from-gta-iv.com/lets_go_bowling.jpg',
    signedUpAt: 1638203719,
    lastSeenAt: 1638203720,
    ownerId: '536e564f316c83104c000021',
    isUnsubscribedFromEmails: true,
});

With Lead Role

const lead = await client.contacts.createLead({
    phone: '[phone]',
    name: 'Roman Bellic',
    avatar: 'https://nico-from-gta-iv.com/lets_go_bowling_yey.jpg',
    signedUpAt: 1638203719,
    lastSeenAt: 1638203720,
    ownerId: '536e564f316c83104c000021',
    isUnsubscribedFromEmails: true,
});

Retrieve a Contact

const response = await client.contacts.find({ id: '123' });

Update a Contact

const response = await client.contacts.update({
    id: '123',
    role: Role.USER,
    name: 'Roman The Bowling Fan',
    customAttributes: {
        callBrother: "Hey Niko, it's me – Roman. Let's go bowling!",
    },
});

Delete a Contact

const response = await client.contacts.delete({ id: '123' });

Archive a Contact

const response = await client.contacts.archive({ id: '123' });

Unarchive a Contact

const response = await client.contacts.unarchive({ id: '123' });

Merge two Contacts

const response = await client.contacts.mergeLeadInUser({
    leadId: '123',
    userId: '234',
});

Search for contacts

const response = await client.contacts.search({
    data: {
        query: {
            operator: Operators.AND,
            value: [
                {
                    operator: Operators.AND,
                    value: [
                        {
                            field: 'updated_at',
                            operator: Operators.GREATER_THAN,
                            value: 1560436650,
                        },
                        {
                            field: 'conversation_rating.rating',
                            operator: Operators.EQUALS,
                            value: 1,
                        },
                    ],
                },
                {
                    operator: Operators.OR,
                    value: [
                        {
                            field: 'updated_at',
                            operator: Operators.GREATER_THAN,
                            value: 1560436650,
                        },
                        {
                            field: 'conversation_rating.rating',
                            operator: Operators.EQUALS,
                            value: 2,
                        },
                    ],
                },
            ],
        },
        pagination: {
            per_page: 5,
            starting_after:
                'WzE2MzU4NjA2NDgwMDAsIjYxODJiNjJlNDM4YjdhM2EwMWE4YWYxNSIsMl0=',
        },
        sort: { field: 'name', order: SearchContactOrderBy.ASC },
    },
});

List all Contacts

With cursor

const response = await client.contacts.list({
    perPage: 5,
    startingAfter:
        'WzE2MzU3NzU4NjkwMDAsIjYxODJiNjJhMDMwZTk4OTBkZWU4NGM5YiIsMl0=',
});

Without a cursor

const response = await client.contacts.list();

List attached companies

const response = await client.contacts.listAttachedCompanies({
    id: '123',
    perPage: 5,
    page: 1,
});

List attached tags

const response = await client.contacts.listAttachedTags({ id: '123' });

List attached segments

const response = await client.contacts.listAttachedSegments({ id: '123' });

List attached email subscriptions

const response = await client.contacts.listAttachedEmailSubscriptions({
    id: '123',
});

Conversations

Create a conversation

const response = await client.conversations.create({
    userId: '123',
    body: 'Hello darkness my old friend',
});

Retrieve a conversation

Formatted text

const response = await client.conversations.find({
    id: '123',
});

As plain text

const response = await client.conversations.find({
    id: '123',
    inPlainText: true,
});

Update a conversation

const response = await client.conversations.update({
    id,
    markRead: true,
    customAttributes: {
        anything: 'you want',
    },
});

Reply to a conversation

By id

As user

const response = await client.conversations.replyByIdAsUser({
    id: '098',
    body: 'blablbalba',
    intercomUserId: '123',
    attachmentUrls: '345',
});

As admin

const response = await client.conversations.replyByIdAsAdmin({
    id: '098',
    adminId: '458',
    messageType: ReplyToConversationMessageType.NOTE,
    body: '<b>Bee C</b>',
    attachmentUrls: ['https://site.org/bebra.jpg'],
});

By last conversation

As user

const response = await client.conversations.replyByLastAsUser({
    body: 'blablbalba',
    intercomUserId: '123',
    attachmentUrls: '345',
});

As admin

const response = await client.conversations.replyByLastAsAdmin({
    adminId: '458',
    messageType: ReplyToConversationMessageType.NOTE,
    body: '<b>Bee C</b>',
    attachmentUrls: ['https://site.org/bebra.jpg'],
});

Assign a conversation

As team without assignment rules

const response = await client.conversations.assign({
    id: '123',
    type: AssignToConversationUserType.TEAM,
    adminId: '456',
    assigneeId: '789',
    body: '<b>blablbalba</b>',
});

As team with assignment rules

const response = await client.conversations.assign({
    id: '123',
    withRunningAssignmentRules: true,
});

Snooze a conversation

const response = await client.conversations.snooze({
    id: '123',
    adminId: '234',
    snoozedUntil: '1501512795',
});

Close a conversation

const response = await client.conversations.close({
    id: '123',
    adminId: '456',
    body: "That's it...",
});

Open a conversation

const response = await client.conversations.open({
    id: '123',
    adminId: '234',
});

Attach a contact to group conversation

As admin, using intercomUserid

const response = await client.conversations.attachContactAsAdmin({
    id: '123',
    adminId: '234',
    customer: {
        intercomUserId: '456',
    },
});

As contact, using intercomUserid

const response = await client.conversations.attachContactAsAdmin({
    id: '123',
    userId: '234',
    customer: {
        intercomUserId: '456',
    },
});

Delete a contact from group conversation as admin

const response = await client.conversations.detachContactAsAdmin({
    conversationId: '123',
    contactId: '456',
    adminId: '789',
});

Search for conversations

const response = await client.conversations.search({
    data: {
        query: {
            operator: Operators.AND,
            value: [
                {
                    operator: Operators.AND,
                    value: [
                        {
                            field: 'updated_at',
                            operator: Operators.GREATER_THAN,
                            value: 1560436650,
                        },
                        {
                            field: 'conversation_rating.rating',
                            operator: Operators.EQUALS,
                            value: 1,
                        },
                    ],
                },
                {
                    operator: Operators.OR,
                    value: [
                        {
                            field: 'updated_at',
                            operator: Operators.GREATER_THAN,
                            value: 1560436650,
                        },
                        {
                            field: 'conversation_rating.rating',
                            operator: Operators.EQUALS,
                            value: 2,
                        },
                    ],
                },
            ],
        },
        pagination: {
            per_page: 5,
            starting_after:
                'WzE2MzU4NjA2NDgwMDAsIjYxODJiNjJlNDM4YjdhM2EwMWE4YWYxNSIsMl0=',
        },
        sort: {
            field: 'name',
            order: SearchConversationOrderBy.DESC,
        },
    },
});

List all conversations

const response = await client.conversations.list({
    startingAfter: 'WzE2NzA0MjI1MjkwMDAsMjQzMTY3NzA2ODcsMl0=',
    perPage: 10,
});

Redact a conversation

const response = await client.conversations.redactConversationPart({
    type: RedactConversationPartType.CONVERSATION_PART,
    conversationId: '123',
    conversationPartId: '456',
});

Counts

App Total Count

const response = await client.counts.forApp();

Conversation Count Model

const response = await client.counts.countConversation();

Admin Conversation Count Model

const response = await client.counts.countAdminConversation();

User Segment/Tag Count Model

Count User Segment

const response = await client.counts.countUserSegment();

Count User Tag

const response = await client.counts.countUserTag();

Company User/Segment/Tag Count Model

Count Company Segment

const response = await client.counts.countCompanySegment();
const response = await client.counts.countCompanyTag();
const response = await client.counts.countCompanyUser();

Count Company Tag

const response = await client.counts.countCompanyTag();

Count Company User

const response = await client.counts.countCompanyUser();

Data Attributes

Create Data Attribute

const response = await client.dataAttributes.create({
    name: 'list_cda',
    model: ModelType.CONTACT,
    dataType: DataType.STRING,
    description: 'You are either alive or dead',
    options: [{ value: 'alive' }, { value: 'dead' }],
});

Update Data Attribute

const response = await client.dataAttributes.update({
    id: '123',
    description: 'You are either alive or dead',
    options: [{ value: 'alive' }, { value: 'dead' }],
    archived: true,
});

List all Data Attributes

const response = await client.dataAttributes.list({
    model: ModelType.CONTACT,
    includeArchived: true,
});

Data Exports

Create a export job

const response = await client.dataExport.create({
    createdAtAfter: 1527811200,
    createdAtBefore: 1530316800,
});

Retrieve a job status

const response = await client.dataExport.find({id: export.id})

Cancel a job

const response = await client.dataExport.cancel({id: export.id})

Events

Submit a data event

const response = await client.events.create({
    eventName: 'placed-order',
    createdAt: 1389913941,
    userId: 'f4ca124298',
    metadata: {
        order_date: 1392036272,
        stripe_invoice: 'inv_3434343434',
        order_number: {
            value: '3434-3434',
            url: 'https://example.org/orders/3434-3434',
        },
        price: {
            currency: 'usd',
            amount: 2999,
        },
    },
});

List all data events

const response = await client.events.listBy({
    userId: '1234',
    perPage: 2,
    summary: true,
    email: '[e-mail]',
});

Help Center - Collections

Create a collection

const collection = await client.helpCenter.collections.create({
    name: 'Thanks for everything',
    description: 'English description',
    translatedContent: {
        fr: {
            name: 'Allez les verts',
            description: 'French description',
        },
    },
});

Retrieve a collection

const response = await client.helpCenter.collections.find({ id: '123' });

Update a collection

const article = await client.helpCenter.collections.update({
    id: '123',
    name: 'Thanks for everything',
    description: 'English description',
    translatedContent: {
        fr: {
            name: 'Allez les verts',
            description: 'French description',
        },
    },
});

Delete a collection

await client.helpCenter.collections.delete({
    id: '123',
});

List all collections

const response = client.helpCenter.collections.list({
    page: 3,
    perPage: 12,
});

Help Center - Sections

Create a section

const collection = await client.helpCenter.sections.create({
    name: 'Thanks for everything',
    parentId: '1234',
    translatedContent: {
        fr: {
            name: 'Allez les verts',
            description: 'French description',
        },
    },
});

Retrieve a section

const response = await client.helpCenter.sections.find({ id: '123' });

Update a section

const article = await client.helpCenter.sections.update({
    id: '123',
    name: 'Thanks for everything',
    parentId: '456',
    translatedContent: {
        fr: {
            name: 'Allez les verts',
            description: 'French description',
        },
    },
});

Delete a section

await client.helpCenter.sections.delete({
    id: '123',
});

List all sections

const response = client.helpCenter.sections.list({
    page: 3,
    perPage: 12,
});

Messages

Create a message

const response = await client.messages.create({
    messageType: 'email',
    subject: 'This is our demand now',
    body: 'Destroy ponies',
    template: 'plain',
    from: {
        type: 'admin',
        id: '394051',
    },
    to: {
        type: 'user',
        id: '536e564f316c83104c000020',
    },
});

Create conversation without contact reply

const response = await client.messages.create({
    messageType: 'inapp',
    body: 'Look at me, I am a conversation now',
    from: {
        type: 'admin',
        id: '394051',
    },
    to: {
        type: 'user',
        id: '536e564f316c83104c000020',
    },
    createConversationWithoutContactReply: true,
});

Notes

Create a note

const response = await client.notes.create({
    adminId: '12345',
    body: 'Shiny',
    contactId: '5678',
});

Retrieve a note

const response = await client.notes.find({ id: '123' });

List all notes

const response = await client.notes.list({
    contactId: '123',
    page: 2,
    perPage: 3,
});

Segments

Retrieve a segment

const response = await client.segments.find({
    id: '123',
    includeCount: true,
});

List all segments

const response = await client.segments.list({
    includeCount: true,
});

Subscriptions

List all subscription types

const response = await client.subscriptions.listTypes();

PhoneCallRedirects

Create a phone call redirect

const response = await client.phoneCallRedirect.create({
    phone: '[phone]',
});

Tags

Create or update a tag

Create

const response = await client.tags.create({ name: 'haven' });

Update

const response = await client.tags.update({ id: '123', name: 'haven' });

Delete a tag

const response = await client.tags.delete({ id: 'baz' });

Attach a contact

const response = await client.tags.tagContact({
    contactId: '123',
    tagId: '234',
});

Attach a conversation

const response = await client.tags.tagConversation({
    conversationId: '123',
    tagId: '456',
    adminId: '789',
});

Tag companies

const response = await client.tags.tagCompanies({
    tagName: 'gutenTag',
    companiesIds: ['123', '234', '456'],
});

Untag companies

const response = await client.tags.untagCompanies({
    tagName: 'gutenTag',
    companiesIds: ['123', '234', '456'],
});

Untag conversation

const response = await client.tags.untagConversation({
    conversationId: '123',
    tagId: '345',
    adminId: '678',
});

Untag contact

const response = await client.tags.untagContact({
    contactId: '123',
    tagId: '345',
});

List all tags

const response = await client.tags.list();

Teams

Retrieve a team

const response = await client.teams.find({
    id: '123',
});

List all teams

const response = await client.teams.list();

Visitors

Retrieve a Visitor

const response = await client.visitors.find({ id: '123' });

OR

const response = await client.visitors.find({ userId: '123' });

Update a Visitor

const response = await client.visitors.update({
    userId: '123',
    name: 'anonymous bruh',
    customAttributes: {
        paid_subscriber: true,
    },
});

Delete a Visitor

const response = await client.visitors.delete({
    id,
});

Convert a Visitor

const response = await client.visitors.mergeToContact({
    visitor: {
        id: '123',
    },
    user: {
        userId: '123',
    },
    type: Role.USER,
});

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

Testing

yarn test

Running the code locally

Compile using babel:

yarn prepublish

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.