Skip to content

intercom/intercom-node

Repository files navigation

intercom-node

Maintenance mode

The Intercom Node SDK is currently in maintenance mode whilst we consider the best way to support it. We are not currently accepting new feature requests or actively working on the SDK.

Circle CI npm Intercom API Version Typescript Supported

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

const admin = await client.admins.find({ id: '123' });
await client.admins.away({
    adminId: '123',
    enableAwayMode: true,
    enableReassignMode: false,
});
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');,
});
const admins = await client.admins.list();

Articles

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',
        },
    },
});
const response = await client.articles.find({ id: '123' });
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',
        },
    },
});
await client.articles.delete({ id: '123' });
const response = await client.articles.list({
    page: 3,
    perPage: 12,
});

Companies

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: {},
});
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: {},
});
By id
const company = await client.companies.find({
    companyId: 123,
});
By name
const company = await client.companies.find({
    name: 'bruh moment inc.',
});
const company = await client.companies.delete({
    id: 62049,
});
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',
});
Using infinite scroll
const companies = await client.companies.scroll.each({});
Using manual scroll
const companies = await client.companies.scroll.next({
    scrollParam: '123_soleil',
});
const response = await client.companies.attachContact({
    contactId: '123',
    companyId: '234',
});
const response = await client.companies.detachContact({
    contactId: '123',
    companyId: '234',
});
const response = await client.companies.listAttachedContacts({
    companyId: '123',
    page: 1,
    perPage: 15,
});
const response = await client.companies.listAttachedSegments({
    companyId: '123',
});

Contacts

With User Role
const user = await client.contacts.createUser({
    externalId: '536e564f316c83104c000020',
    phone: '+48370044567',
    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: '+48370044567',
    name: 'Roman Bellic',
    avatar: 'https://nico-from-gta-iv.com/lets_go_bowling_yey.jpg',
    signedUpAt: 1638203719,
    lastSeenAt: 1638203720,
    ownerId: '536e564f316c83104c000021',
    isUnsubscribedFromEmails: true,
});
const response = await client.contacts.find({ id: '123' });
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!",
    },
});
const response = await client.contacts.delete({ id: '123' });
const response = await client.contacts.archive({ id: '123' });
const response = await client.contacts.unarchive({ id: '123' });
const response = await client.contacts.mergeLeadInUser({
    leadId: '123',
    userId: '234',
});
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 },
    },
});
With cursor
const response = await client.contacts.list({
    perPage: 5,
    startingAfter:
        'WzE2MzU3NzU4NjkwMDAsIjYxODJiNjJhMDMwZTk4OTBkZWU4NGM5YiIsMl0=',
});
Without a cursor
const response = await client.contacts.list();
const response = await client.contacts.listAttachedCompanies({
    id: '123',
    perPage: 5,
    page: 1,
});
const response = await client.contacts.listAttachedTags({ id: '123' });
const response = await client.contacts.listAttachedSegments({ id: '123' });
const response = await client.contacts.listAttachedEmailSubscriptions({
    id: '123',
});

Conversations

const response = await client.conversations.create({
    userId: '123',
    body: 'Hello darkness my old friend',
});
Formatted text
const response = await client.conversations.find({
    id: '123',
});
As plain text
const response = await client.conversations.find({
    id: '123',
    inPlainText: true,
});
const response = await client.conversations.update({
    id,
    markRead: true,
    customAttributes: {
        anything: 'you want',
    },
});
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'],
});
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,
});
const response = await client.conversations.snooze({
    id: '123',
    adminId: '234',
    snoozedUntil: '1501512795',
});
const response = await client.conversations.close({
    id: '123',
    adminId: '456',
    body: "That's it...",
});
const response = await client.conversations.open({
    id: '123',
    adminId: '234',
});
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',
    },
});
const response = await client.conversations.detachContactAsAdmin({
    conversationId: '123',
    contactId: '456',
    adminId: '789',
});
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,
        },
    },
});
const response = await client.conversations.list({
    startingAfter: 'WzE2NzA0MjI1MjkwMDAsMjQzMTY3NzA2ODcsMl0=',
    perPage: 10,
});
const response = await client.conversations.redactConversationPart({
    type: RedactConversationPartType.CONVERSATION_PART,
    conversationId: '123',
    conversationPartId: '456',
});

Counts

const response = await client.counts.forApp();
const response = await client.counts.countConversation();
const response = await client.counts.countAdminConversation();
Count User Segment
const response = await client.counts.countUserSegment();
Count User Tag
const response = await client.counts.countUserTag();
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

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' }],
});
const response = await client.dataAttributes.update({
    id: '123',
    description: 'You are either alive or dead',
    options: [{ value: 'alive' }, { value: 'dead' }],
    archived: true,
});
const response = await client.dataAttributes.list({
    model: ModelType.CONTACT,
    includeArchived: true,
});

Data Exports

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

Events

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,
        },
    },
});
const response = await client.events.listBy({
    userId: '1234',
    perPage: 2,
    summary: true,
    email: '[email protected]',
});

Help Center - Collections

const collection = await client.helpCenter.collections.create({
    name: 'Thanks for everything',
    description: 'English description',
    translatedContent: {
        fr: {
            name: 'Allez les verts',
            description: 'French description',
        },
    },
});
const response = await client.helpCenter.collections.find({ id: '123' });
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',
        },
    },
});
await client.helpCenter.collections.delete({
    id: '123',
});
const response = client.helpCenter.collections.list({
    page: 3,
    perPage: 12,
});

Help Center - Sections

const collection = await client.helpCenter.sections.create({
    name: 'Thanks for everything',
    parentId: '1234',
    translatedContent: {
        fr: {
            name: 'Allez les verts',
            description: 'French description',
        },
    },
});
const response = await client.helpCenter.sections.find({ id: '123' });
const article = await client.helpCenter.sections.update({
    id: '123',
    name: 'Thanks for everything',
    parentId: '456',
    translatedContent: {
        fr: {
            name: 'Allez les verts',
            description: 'French description',
        },
    },
});
await client.helpCenter.sections.delete({
    id: '123',
});
const response = client.helpCenter.sections.list({
    page: 3,
    perPage: 12,
});

Messages

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

const response = await client.notes.create({
    adminId: '12345',
    body: 'Shiny',
    contactId: '5678',
});
const response = await client.notes.find({ id: '123' });
const response = await client.notes.list({
    contactId: '123',
    page: 2,
    perPage: 3,
});

Segments

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

Subscriptions

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

PhoneCallRedirects

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

Tags

Create
const response = await client.tags.create({ name: 'haven' });
Update
const response = await client.tags.update({ id: '123', name: 'haven' });
const response = await client.tags.delete({ id: 'baz' });
const response = await client.tags.tagContact({
    contactId: '123',
    tagId: '234',
});
const response = await client.tags.tagConversation({
    conversationId: '123',
    tagId: '456',
    adminId: '789',
});
const response = await client.tags.tagCompanies({
    tagName: 'gutenTag',
    companiesIds: ['123', '234', '456'],
});
const response = await client.tags.untagCompanies({
    tagName: 'gutenTag',
    companiesIds: ['123', '234', '456'],
});
const response = await client.tags.untagConversation({
    conversationId: '123',
    tagId: '345',
    adminId: '678',
});
const response = await client.tags.untagContact({
    contactId: '123',
    tagId: '345',
});
const response = await client.tags.list();

Teams

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

Visitors

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

OR

const response = await client.visitors.find({ userId: '123' });
const response = await client.visitors.update({
    userId: '123',
    name: 'anonymous bruh',
    customAttributes: {
        paid_subscriber: true,
    },
});
const response = await client.visitors.delete({
    id,
});
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: '[email protected]',
});

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.