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: '+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,
});
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: '[email protected]',
});
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: '+353871234567',
});
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: '[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.