Intercom

Let hires search and read Intercom conversations, reply to customers or leave internal notes, assign, close or snooze, look up customers, and be woken when conversations change.

Explore 9 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Intercom connected, a hire can:

search conversations by state (open, closed, snoozed), words in the customer's first message, the teammate or team assigned, or what changed since a time,
read a conversation with every message, internal notes marked,
reply to the customer, or leave an internal note only your team sees,
assign a conversation to a teammate or a team, close it, reopen it or snooze it until a time,
look up customers by name or email.

Want to try it first?

Intercom (quick connect) connects in one click, with nothing to make in Intercom: you sign in and approve Roster. It's limited: hires can read conversations and contacts and add internal notes, but can't reply to customers, can't be held to teams, and it works only for workspaces hosted in the US or Europe. Pick this page's Intercom when hires should reply, assign, close or snooze, stay inside their teams, or your workspace is hosted in Australia. You can connect both, and give each hire the one its work needs.

1. Choose who hires reply as

Replies show to your customers under the name of an Intercom teammate. Use a teammate named after your team, like Bayt Studio Support, never a made-up person's name. Sign in to Intercom as that teammate for the next step: the access token acts as whoever made the app.

Then either:

An access token (quickest): open the Developer Hub, click New app, name it Roster and choose your workspace. Under Configure → Authentication, make sure it may read and list users and companies, read and write conversations, and read teammates, then copy the Access token. This app stays private to your workspace.
Your own OAuth app: in the same Developer Hub app, under Configure → Authentication, turn on OAuth, put the callback address Roster shows on the connection as its redirect URL, and copy its client ID and secret.

If your workspace is hosted in Europe or Australia, sign in at app.eu.intercom.com or app.au.intercom.com first.

2. Connect it in Roster

Open Integrations → Tools → Add a tool, search for Intercom and choose it.
How Roster signs in: An access token (paste it), or An OAuth app of yours (paste its client ID and secret, then Connect).
Where your workspace is hosted: United States, Europe or Australia.
Teammate replies show as: that teammate's email, like support@bayt.example.
Business name: your business's name, like Bayt Studio.
Customers' contact details: Masked (the default) shows hires only the domain of a customer's email, like l***@client.example, and no phone number. Shown shows both in full.
Click Connect. Roster shows which workspace and teammate the token belongs to.

3. Give hires access

On the hire's Tools tab, click Give access on Intercom:

Read only: it can search and read conversations, look up customers and see teams, and nothing else.
Read and write: it can also reply, leave notes, assign, close, reopen and snooze.
Teams: team names or IDs whose conversations it may see and work on. Leave it empty for every team. A conversation assigned to any other team, or to no team, is refused, even if the hire knows its ID, and it can't hand a conversation to a team outside the list.

Customers' details are kept to what helps with the conversation: name, company, country, when they were last seen, and custom attributes that aren't personal details (addresses, phone numbers and the like are left out).

First replies wait for approval

The first reply a hire writes to a customer it has never written to waits for a person's approval, even though they wrote in first. If a teammate already replied in the conversation, it doesn't ask. The hire asks in the thread with the conversation and the reply, and when the approver says yes, Roster posts exactly that reply, once. After that, replies to that customer go out without asking. Internal notes never ask, and neither do replies to people at your team's own domains.

Customers your team already talks to can be added under Settings → Workspace → People you're already in touch with (more). Approving a first reply adds the customer's address there too.

Watching conversations

A hire's responsibility can watch Intercom: it's woken when a conversation in its teams starts or changes, with the list. When nothing changed, nothing runs.

Saying it's an AI assistant

A hire never pretends to be a person, and always says it's AI when asked. If you also want it to say so up front, turn on Say it's an AI assistant in first messages to outsiders under Settings → Workspace (more). Then the team's first reply in a conversation starts with "This is the AI assistant for" and your business name. Internal notes are never changed.

If something goes wrong

"Intercom returned 401": the token was regenerated or the app uninstalled. Copy the new token onto the connection.
"No Intercom teammate is …": the teammate in Teammate replies show as isn't in the workspace any more. Put the right email on the connection.
Nothing found that you can see in Intercom: check Where your workspace is hosted.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Intercom and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In Intercom: Settings → Integrations → Developer Hub → your app → Configure → Authentication → Access token.

For: How Roster signs in: An access token.

OAuth 2.0

From the app you made in Intercom's Developer Hub (Configure → Authentication), with Roster's callback address as its redirect URL.

For: How Roster signs in: An OAuth app of yours.

When making a key, use these permissions from the connection guide:

Read and list users and companies
Read and write conversations
Read admins

Connection fields

Intercom connection fields
Field	What to provide
How Roster signs in `signIn` Optional	An access token from an app in your Developer Hub is quickest. An OAuth app of yours works too. Choices: An access token (token); An OAuth app of yours (oauth). Starts with: `token`.
Access token `token` Required · sealed secret	In Intercom: Settings → Integrations → Developer Hub → your app → Configure → Authentication → Access token. Shown when `signIn: token`.
OAuth app client ID `clientId` Optional	From the app you made in Intercom's Developer Hub (Configure → Authentication), with Roster's callback address as its redirect URL. Shown when `signIn: oauth`.
OAuth app client secret `clientSecret` Optional · sealed secret	Use the value for your account or connection. Shown when `signIn: oauth`.
Where your workspace is hosted `region` Optional	The region your Intercom workspace is in: app.intercom.com is US, app.eu.intercom.com Europe, app.au.intercom.com Australia. Choices: United States (us); Europe (eu); Australia (au). Starts with: `us`.
Teammate replies show as `replyAs` Required	The email (or ID) of the Intercom teammate whose name customers see on replies. Make one named for your team, like Bayt Studio Support, never a made-up person.
Business name `businessName` Required	Used when hires say they're your business's AI assistant. Never a made-up person's name.
Customers' contact details `contactDetails` Optional	Masked: hires see the domain of a customer's email (j***@client.com) and no phone number. Shown: the full email and phone. Choices: Masked (masked); Shown (shown). Starts with: `masked`.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Intercom per-hire limits
Field	What to provide
Teams `teams` Optional	Team names or IDs whose conversations it may see and work on. Leave empty for every team.

Actions

9 actions: 5 only read and 4 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

Find an actionAccess

9 of 9 actions. Open an action for its arguments and full input schema.

search_conversationsRead only

Search conversations, most recently updated first: by state (open, closed, snoozed), words in the customer's first message, the teammate or team assigned, or changed since a time.

Approval: Uses your workspace and hire approval settings.

Arguments for search_conversations
Argument	Type	Details
`state`Optional	"open" \| "closed" \| "snoozed" \| "any"	See input schema below.Default: `"open"`
`words`Optional	string	words in the conversation's first message
`assignee`Optional	string	a teammate's email or name, or "none" for unassigned
`team`Optional	string	a team's name
`changedSince`Optional	string	See input schema below.
`limit`Optional	integer	See input schema below.Default: `20`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "state": {
      "default": "open",
      "type": "string",
      "enum": [
        "open",
        "closed",
        "snoozed",
        "any"
      ]
    },
    "words": {
      "description": "words in the conversation's first message",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "assignee": {
      "description": "a teammate's email or name, or \"none\" for unassigned",
      "type": "string"
    },
    "team": {
      "description": "a team's name",
      "type": "string"
    },
    "changedSince": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}

read_conversationRead only

Read a conversation: its details and every message oldest first, internal notes marked, with who wrote each.

Approval: Uses your workspace and hire approval settings.

Arguments for read_conversation
Argument	Type	Details
`id`Required	string	the conversation's id

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the conversation's id"
    }
  },
  "required": [
    "id"
  ]
}

replyRead and write

Reply to the customer in a conversation (they see it in the Messenger or by email). It goes out in the business's name: write as the business, never sign with a person's name or say you're one.

Approval: when it writes to someone outside your team for the first time.

Arguments for reply
Argument	Type	Details
`id`Required	string	the conversation's id
`text`Required	string	See input schema below.
`close`Optional	boolean	close the conversation after replyingDefault: `false`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the conversation's id"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000
    },
    "close": {
      "default": false,
      "description": "close the conversation after replying",
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "text"
  ]
}

add_noteRead and write

Leave an internal note in a conversation, for the team only; the customer never sees it.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
Argument	Type	Details
`id`Required	string	the conversation's id
`text`Required	string	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the conversation's id"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000
    }
  },
  "required": [
    "id",
    "text"
  ]
}

set_stateRead and write

Close, reopen or snooze a conversation (snoozing until a time, when it reopens by itself).

Approval: Uses your workspace and hire approval settings.

Arguments for set_state
Argument	Type	Details
`id`Required	string	the conversation's id
`state`Required	"open" \| "closed" \| "snoozed"	See input schema below.
`until`Optional	string	for snoozed: when it reopens

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the conversation's id"
    },
    "state": {
      "type": "string",
      "enum": [
        "open",
        "closed",
        "snoozed"
      ]
    },
    "until": {
      "description": "for snoozed: when it reopens",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "id",
    "state"
  ]
}

assignRead and write

Assign a conversation to a teammate (by email or name) and/or a team (by name). Only teams this hire may use.

Approval: Uses your workspace and hire approval settings.

Arguments for assign
Argument	Type	Details
`id`Required	string	the conversation's id
`teammate`Optional	string	a teammate's email or name, or "none" to unassign
`team`Optional	string	a team's name

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the conversation's id"
    },
    "teammate": {
      "description": "a teammate's email or name, or \"none\" to unassign",
      "type": "string"
    },
    "team": {
      "description": "a team's name",
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

find_contactsRead only

Find customers (contacts) by name or email: name, role, company, country and when last seen. Contact details are masked unless the connection shows them.

Approval: Uses your workspace and hire approval settings.

Arguments for find_contacts
Argument	Type	Details
`name`Optional	string	See input schema below.
`email`Optional	string	their exact email address
`limit`Optional	integer	See input schema below.Default: `10`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "email": {
      "description": "their exact email address",
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}

get_contactRead only

One customer (contact) by id: name, role, company, country, when they signed up and were last seen, and custom attributes that aren't personal details.

Approval: Uses your workspace and hire approval settings.

Arguments for get_contact
Argument	Type	Details
`id`Required	string	the contact's id

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[\\w-]{1,64}$",
      "description": "the contact's id"
    }
  },
  "required": [
    "id"
  ]
}

list_teamsRead only

The Intercom teams this hire may use, and the teammates in the workspace.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}

Watches and incoming events

This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
No incoming webhook handler is declared for this integration.

Limits and troubleshooting

Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
Expired or revoked access: reconnect or replace the key on the connection.
Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

1. Choose who hires reply asCopy Anchor Link

2. Connect it in RosterCopy Anchor Link

3. Give hires accessCopy Anchor Link

First replies wait for approvalCopy Anchor Link

Saying it's an AI assistantCopy Anchor Link

If something goes wrongCopy Anchor Link

Tools and permissions reference

Authentication and requested permissions

API key or access token

OAuth 2.0

Connection fields

Per-hire limits

Actions

Watches and incoming events

Limits and troubleshooting

On this page

1. Choose who hires reply as

2. Connect it in Roster

3. Give hires access

First replies wait for approval

Saying it's an AI assistant

If something goes wrong