Intercom

Customer messaging and support: contacts, notes and conversations. Works with US-hosted Intercom workspaces.

10 actions OAuth 2 6 read4 write Calls api.intercom.io

Connect

TypeScript

const conn = await setu.connections.initiate({ userId: "user_1", toolkit: "intercom" });
console.log(conn.connectUrl); // show this to your user
await conn.waitUntilActive();

Permissions requested

Scope	Why it is requested
`read_contacts`	Read your Intercom contacts and notes
`write_contacts`	Create and update Intercom contacts and notes
`read_conversations`	Read your Intercom conversations
`write_conversations`	Reply to Intercom conversations

Actions

Create contactwriteintercom.create_contactCreate a contact (a user or a lead) with an email, name, phone, external id or custom attributes. Fails if one with that email already exists.

Needs scope: write_contacts

Input	Type		Description
`role`	string	Optional	user or lead
`email`	string	Optional
`name`	string	Optional
`phone`	string	Optional	Phone number in E.164 format
`external_id`	string	Optional	Your own id for this contact
`custom_attributes`	object	Optional	Custom data attributes defined in the workspace

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.create_contact",
  input: {},
});

Add note to contactwriteintercom.create_noteAdd an internal note to a contact's record. Needs the id of the teammate who is the author (see list_admins).

Needs scope: write_contacts

Input	Type		Description
`contact_id`	string	Required	Intercom contact id
`body`	string	Required	Note text
`admin_id`	string	Optional	Author admin id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.create_note",
  input: {
    "contact_id": "<contact_id>",
    "body": "<body>"
  },
});

Get contactreadintercom.get_contactGet one contact (user or lead) by its Intercom id.

Needs scope: read_contacts

Input	Type		Description
`contact_id`	string	Required	Intercom contact id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.get_contact",
  input: {
    "contact_id": "<contact_id>"
  },
});

Get conversationreadintercom.get_conversationGet a conversation by id, including its messages (conversation parts) and state.

Needs scope: read_conversations

Input	Type		Description
`conversation_id`	string	Required	Conversation id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.get_conversation",
  input: {
    "conversation_id": "<conversation_id>"
  },
});

List adminsreadintercom.list_adminsList the workspace's teammates (admins) with their ids, needed as admin_id when adding notes or replying.

Needs scope: read_conversations

No input.

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.list_admins",
  input: {},
});

List conversationsreadintercom.list_conversationsList recent conversations, newest first by default, with their state (open, closed, snoozed). Use starting_after to page.

Needs scope: read_conversations

Input	Type		Description
`per_page`	integer	Optional	Page size, up to 150
`starting_after`	string	Optional	Cursor from pages.next.starting_after of the previous page

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.list_conversations",
  input: {},
});

Reply to conversationwriteintercom.reply_to_conversationReply as a teammate to a conversation: message_type comment sends a reply the customer sees, note adds an internal note. Needs the admin_id of the author.

Needs scope: write_conversations

Input	Type		Description
`conversation_id`	string	Required	Conversation id
`message_type`	string	Required	comment is visible to the customer, note is internal
`admin_id`	string	Required	Author admin id (see list_admins)
`body`	string	Required	Reply text

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.reply_to_conversation",
  input: {
    "conversation_id": "<conversation_id>",
    "message_type": "<message_type>",
    "admin_id": "<admin_id>",
    "body": "<body>"
  },
});

Search contactsreadintercom.search_contactsSearch contacts (users and leads) with Intercom's query syntax, for example {field: email, operator: =, value: [email protected]}. Combine several with AND or OR.

Needs scope: read_contacts

Input	Type		Description
`query`	object	Required	Either a single filter {field, operator, value} or {operator: AND\|OR, value: [filters]}. Operators: =, !=, IN, NIN, <, >, ~, !~, ^, $.
`per_page`	integer	Optional	Page size, up to 150

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.search_contacts",
  input: {
    "query": {}
  },
});

Search conversationsreadintercom.search_conversationsSearch conversations with Intercom's query syntax, for example open conversations assigned to an admin: {field: state, operator: =, value: open}.

Needs scope: read_conversations

Input	Type		Description
`query`	object	Required	Either a single filter {field, operator, value} or {operator: AND\|OR, value: [filters]}. Fields include state, open, created_at, updated_at, source.body.
`per_page`	integer	Optional	Page size, up to 150

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.search_conversations",
  input: {
    "query": {}
  },
});

Update contactwriteintercom.update_contactUpdate fields on an existing contact by id. Only the fields you pass change.

Needs scope: write_contacts

Input	Type		Description
`contact_id`	string	Required	Intercom contact id
`role`	string	Optional	user or lead
`email`	string	Optional
`name`	string	Optional
`phone`	string	Optional	Phone number in E.164 format
`external_id`	string	Optional	Your own id for this contact
`custom_attributes`	object	Optional	Custom data attributes defined in the workspace

TypeScript

await setu.execute({
  userId: "user_1",
  action: "intercom.update_contact",
  input: {
    "contact_id": "<contact_id>"
  },
});