# Intercom

Manage Intercom contacts and companies, reply to, assign and close conversations, handle tickets, and publish help center articles.

## Connect Intercom

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `intercom` and choose **Intercom**.
3. Choose **Sign in with Intercom**.
4. Press **Sign in with Intercom** at the bottom of the sheet, then choose your account in Intercom’s window and allow access.

Or choose **Paste your access token**, paste it, and press **Test and save**. It stays until someone deletes it.

Sign in with Intercom, or paste the access token of an app in your workspace (Developer Hub › your app › Configure › Authentication). Set the region your workspace’s data is hosted in.

**What if it says “Sign-in isn’t set up here yet”?**

Signing in with Intercom needs a Intercom app on this installation, and it has none yet. Until it is set up, **Paste your access token** works without it.

**On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.”

**Self-hosted:** An admin of the installation sees **Set up Intercom sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask.

1. Create an app in Intercom’s developer settings ([Intercom’s guide](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication)).
2. In GoRunner, copy the **Redirect address to add in Intercom’s developer settings**, and add it to the app.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

[Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers)

**Can I use my own Intercom app?**

Yes. In the sheet, open **Use your own Intercom app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Intercom**. The trigger uses the same connection as the steps.

### On Conversation or Contact Created or Updated

Checks Intercom about once a minute and starts a run for each conversation or contact created, or each change to one, since the check before, oldest first. The first check after publishing only takes note of what is there (it starts nothing); changing the trigger starts over the same way. Several changes between two checks start one run, with the record as it is then. At most 100 runs start per check; the rest follow on the next one. (Intercom sends webhooks only to one address per app, set in its Developer Hub, so this trigger checks instead.).

- **Trigger on · Required**: What starts a run. Options: New conversation, Conversation updated (a reply, note, assignment, state change …), New contact, Contact updated. Default: New conversation.
- **Contact Role · Optional**: Only users, or only leads. Empty: both. Options: Users, Leads. Shows when **Trigger on** is **New contact** or **Contact updated**.

A later step can use its data, such as `{{trigger.change_type}}`, `{{trigger.created_at}}`, `{{trigger.email}}` and 5 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Intercom

Add an **Intercom** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Contact](https://docs.gorunner.io/apps/intercom#fields-f-contact): Create · Get · Get Many · Search · Update · Delete · Add Tag · Remove Tag · Attach to Company · Add Note · Merge Lead into User
- [Company](https://docs.gorunner.io/apps/intercom#fields-f-company): Create or Update · Get · Get Many · Update · Delete · Get Contacts · Add Tag · Remove Tag
- [Conversation](https://docs.gorunner.io/apps/intercom#fields-f-conversation): Create · Get · Get Many · Search · Reply · Add Note · Assign · Close · Reopen · Snooze · Add Tag · Remove Tag
- [Ticket](https://docs.gorunner.io/apps/intercom#fields-f-ticket): Create · Get · Search · Update · Reply · Delete
- [Article](https://docs.gorunner.io/apps/intercom#fields-f-article): Create · Get · Get Many · Search · Update · Delete
- [Data Attribute](https://docs.gorunner.io/apps/intercom#fields-f-dataattribute): Get Many · Create · Update
- [Tag](https://docs.gorunner.io/apps/intercom#fields-f-tag): Get Many · Create · Delete
- [Admin](https://docs.gorunner.io/apps/intercom#fields-f-admin): Get Many · Get

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Intercom can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Intercom says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Intercom is `pieceId: "intercom"` with `actionId: "intercom"`, set by `resource` and an `operation_…` field, such as `operation_admin`. Its trigger is `intercomtrigger` / `intercom_poll`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Intercom › Contact

### Create

- **Role · Optional**: A user (signed up) or a lead (not yet). Empty: user on create, unchanged on update (a lead can become a user). Options: User, Lead.
- **Email · Optional**: Create needs an Email, an External ID, or the Lead role.
- **External ID · Optional**: The person's id in your own system (users only).
- **Name · Optional**
- **Phone · Optional**
- **Avatar URL · Optional**: An image of the person.
- **Owner · Optional**: The admin who owns the contact.
- **Signed Up At · Optional**: ISO 8601 or Unix seconds.
- **Last Seen At · Optional**: ISO 8601 or Unix seconds.
- **Unsubscribed from Emails · Optional**: Options: Unsubscribed, Subscribed.
- **Custom Attributes · Optional**: Values of your contact data attributes by name: {"plan": "pro"}. Data Attribute › Get Many lists them.

### Get and Delete

- **Contact ID · Required**: The contact's Intercom id, or their link in Intercom.

### Get Many

- **Return All · Optional**: Read every contact, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many contacts to return (1–2000). Default: 50. Shows when **Return All** is off.

### Search

- **Email · Optional**: Find contacts with this email (instead of a Filter).
- **Filter · Optional**: Or a full Intercom query, such as {"field": "role", "operator": "=", "value": "lead"}. one condition {"field": "email", "operator": "=", "value": "sam@example.com"} or a group {"operator": "AND", "value": [ … ]}. Operators: =!= in NIN > \< ~!~ ^ $. Times are Unix seconds.
- **Sort By · Optional**: A field to sort by, such as updated_at or created_at.
- **Sort Order · Optional**: Options: Ascending, Descending.
- **Return All · Optional**: Read every contact, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many contacts to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Contact ID · Required**: The contact's Intercom id, or their link in Intercom.
- **Role · Optional**: A user (signed up) or a lead (not yet). Empty: user on create, unchanged on update (a lead can become a user). Options: User, Lead.
- **Email · Optional**: Create needs an Email, an External ID, or the Lead role.
- **External ID · Optional**: The person's id in your own system (users only).
- **Name · Optional**
- **Phone · Optional**
- **Avatar URL · Optional**: An image of the person.
- **Owner · Optional**: The admin who owns the contact.
- **Signed Up At · Optional**: ISO 8601 or Unix seconds.
- **Last Seen At · Optional**: ISO 8601 or Unix seconds.
- **Unsubscribed from Emails · Optional**: Options: Unsubscribed, Subscribed.
- **Custom Attributes · Optional**: Values of your contact data attributes by name: {"plan": "pro"}. Data Attribute › Get Many lists them.

### Add Tag and Remove Tag

- **Contact ID · Required**: The contact's Intercom id, or their link in Intercom.
- **Tag · Required**: The tag.

### Attach to Company

- **Contact ID · Required**: The contact's Intercom id, or their link in Intercom.
- **Company ID · Required**: The company's Intercom id (not your company_id).

### Add Note

- **Contact ID · Required**: The contact's Intercom id, or their link in Intercom.
- **Note · Required**: The note's text (HTML allowed).
- **Admin · Optional**: Who writes the note. Empty: the admin the connection acts as.

### Merge Lead into User

- **Lead ID · Required**: The lead to merge (it is removed).
- **User ID · Required**: The user it is merged into.

### Intercom › Company

### Create or Update

- **Company ID · Optional**: The company's id in your own system. Create or Update finds the company by it, and adds it when there is none.
- **Name · Optional**
- **Plan · Optional**
- **Size · Optional**: Number of employees.
- **Website · Optional**
- **Industry · Optional**
- **Monthly Spend · Optional**: How much the company pays you a month (a whole number).
- **Created At (yours) · Optional**: When the company was created in your system: ISO 8601 or Unix seconds.
- **Custom Attributes · Optional**: Values of your company data attributes by name: {"tier": "gold"}.

### Get

- **Find By · Optional**: Options: Intercom ID, Company ID (yours), Name.
- **Value · Required**: The id or name to find the company by.

### Get Many

- **Return All · Optional**: Read every item, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many items to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Company ID · Required**: The company's Intercom id, or its link in Intercom.
- **Name · Optional**
- **Plan · Optional**
- **Size · Optional**: Number of employees.
- **Website · Optional**
- **Industry · Optional**
- **Monthly Spend · Optional**: How much the company pays you a month (a whole number).
- **Created At (yours) · Optional**: When the company was created in your system: ISO 8601 or Unix seconds.
- **Custom Attributes · Optional**: Values of your company data attributes by name: {"tier": "gold"}.

### Delete

- **Company ID · Required**: The company's Intercom id, or its link in Intercom.

### Get Contacts

- **Company ID · Required**: The company's Intercom id, or its link in Intercom.
- **Return All · Optional**: Read every item, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many items to return (1–2000). Default: 50. Shows when **Return All** is off.

### Add Tag and Remove Tag

- **Company ID · Required**: The company's Intercom id, or its link in Intercom.
- **Tag · Required**: The tag's name (adding a name that does not exist yet makes the tag).

### Intercom › Conversation

### Create

- **Contact ID · Required**: The user or lead the conversation is from.
- **Message · Required**: The text (HTML allowed in replies and notes).

### Get

- **Conversation ID · Required**: The conversation's id, or its link in the Intercom inbox.
- **Plain Text · Optional**: Return the messages as plain text instead of HTML. Off by default.

### Get Many

- **Return All · Optional**: Read every conversation, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many conversations to return (1–2000). Default: 50. Shows when **Return All** is off.

### Search

- **Filter · Required**: Intercom's search query: one condition {"field": "email", "operator": "=", "value": "sam@example.com"} or a group {"operator": "AND", "value": [ … ]}. Operators: =!= in NIN > \< ~!~ ^ $. Times are Unix seconds.
- **Sort By · Optional**: A field to sort by, such as updated_at or created_at.
- **Sort Order · Optional**: Options: Ascending, Descending.
- **Return All · Optional**: Read every conversation, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many conversations to return (1–2000). Default: 50. Shows when **Return All** is off.

### Reply

- **Conversation ID · Required**: The conversation's id, or its link in the Intercom inbox.
- **Message · Required**: The text (HTML allowed in replies and notes).
- **Reply As · Optional**: An admin's reply in the inbox, or a message from the contact. Options: Admin, The contact.
- **Contact ID · Optional**: The contact who writes (Reply As The contact). Shows when **Reply As** is **The contact**.
- **Attachment URLs · Optional**: Links to files to attach (up to 10), separated by commas.
- **Admin · Optional**: Who acts. Empty: the admin the connection acts as.

### Add Note

- **Conversation ID · Required**: The conversation's id, or its link in the Intercom inbox.
- **Message · Required**: The text (HTML allowed in replies and notes).
- **Attachment URLs · Optional**: Links to files to attach (up to 10), separated by commas.
- **Admin · Optional**: Who acts. Empty: the admin the connection acts as.

### Assign

- **Conversation ID · Required**: The conversation's id, or its link in the Intercom inbox.
- **Assign To · Required**: The admin or team (0: unassigned).
- **Message · Optional**: An optional note with the change.
- **Admin · Optional**: Who acts. Empty: the admin the connection acts as.

### Close

- **Conversation ID · Required**: The conversation's id, or its link in the Intercom inbox.
- **Message · Optional**: An optional note with the change.
- **Admin · Optional**: Who acts. Empty: the admin the connection acts as.

### Reopen

- **Conversation ID · Required**: The conversation's id, or its link in the Intercom inbox.
- **Admin · Optional**: Who acts. Empty: the admin the connection acts as.

### Snooze

- **Conversation ID · Required**: The conversation's id, or its link in the Intercom inbox.
- **Snooze Until · Required**: When it reopens: ISO 8601 or Unix seconds.
- **Admin · Optional**: Who acts. Empty: the admin the connection acts as.

### Add Tag and Remove Tag

- **Conversation ID · Required**: The conversation's id, or its link in the Intercom inbox.
- **Tag · Required**: The tag.
- **Admin · Optional**: Who acts. Empty: the admin the connection acts as.

### Intercom › Ticket

### Create

- **Ticket Type · Required**: The kind of ticket (Settings › Tickets).
- **Contact ID · Optional**: Who the ticket is for. Create needs this or a Contact Email.
- **Contact Email · Optional**: Or the contact's email (Intercom adds a lead when it is new).
- **Title · Optional**: The ticket's title.
- **Description · Optional**: The ticket's description.
- **Ticket Attributes · Optional**: More of the ticket type's attributes by name: {"Priority": "High"}.
- **Company ID · Optional**: The company the ticket belongs to (its Intercom id).

### Get and Delete

- **Ticket ID · Required**: The ticket's id (from the API or the trigger: not the #number the inbox shows).

### Search

- **Filter · Required**: Intercom's search query: one condition {"field": "email", "operator": "=", "value": "sam@example.com"} or a group {"operator": "AND", "value": [ … ]}. Operators: =!= in NIN > \< ~!~ ^ $. Times are Unix seconds.
- **Sort By · Optional**: A field to sort by, such as updated_at or created_at.
- **Sort Order · Optional**: Options: Ascending, Descending.
- **Return All · Optional**: Read every ticket, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many tickets to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Ticket ID · Required**: The ticket's id (from the API or the trigger: not the #number the inbox shows).
- **Title · Optional**: The ticket's title.
- **Description · Optional**: The ticket's description.
- **Ticket Attributes · Optional**: More of the ticket type's attributes by name: {"Priority": "High"}.
- **Company ID · Optional**: The company the ticket belongs to (its Intercom id).
- **State · Optional**: The ticket's state.
- **Open · Optional**: Closed: closes (and unsnoozes) the ticket. Options: Open, Closed.
- **Assign To · Optional**: The admin or team (0: unassigned).
- **Snooze Until · Optional**: ISO 8601 or Unix seconds.
- **Admin · Optional**: Who acts. Empty: the admin the connection acts as.

### Reply

- **Ticket ID · Required**: The ticket's id (from the API or the trigger: not the #number the inbox shows).
- **Message · Required**: The reply or note (HTML allowed).
- **Kind · Optional**: A reply the customer sees, or an internal note. Options: Reply, Note.
- **Admin · Optional**: Who acts. Empty: the admin the connection acts as.

### Intercom › Article

### Create

- **Title · Optional**: Required to create an article.
- **Body · Optional**: The article (HTML).
- **Description · Optional**: A short summary shown under the title.
- **Author · Optional**: The admin who wrote it. Empty on create: the admin the connection acts as.
- **State · Optional**: Empty: draft on create, unchanged on update. Options: Draft, Published.
- **Collection ID · Optional**: The help center collection it sits in.

### Get and Delete

- **Article ID · Required**: The article's id.

### Get Many

- **Return All · Optional**: Read every article, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many articles to return (1–2000). Default: 50. Shows when **Return All** is off.

### Search

- **Search Text · Required**: Words in the articles.
- **State · Optional**: Options: Draft, Published.
- **Return All · Optional**: Read every article, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many articles to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Article ID · Required**: The article's id.
- **Title · Optional**: Required to create an article.
- **Body · Optional**: The article (HTML).
- **Description · Optional**: A short summary shown under the title.
- **Author · Optional**: The admin who wrote it. Empty on create: the admin the connection acts as.
- **State · Optional**: Empty: draft on create, unchanged on update. Options: Draft, Published.
- **Collection ID · Optional**: The help center collection it sits in.

### Intercom › Data Attribute

### Get Many

- **Of · Optional**: Whose attributes. Options: Contacts, Companies.
- **Include Archived · Optional**: Off by default.

### Create

- **Of · Optional**: Whose attributes. Options: Contacts, Companies.
- **Name · Required**: The attribute's name.
- **Type · Required**: Options: Text, Whole number, Decimal number, True or false, Date and time, Date. Default: Text.
- **Description · Optional**
- **Options · Optional**: For a text attribute picked from a list: the values, separated by commas.
- **Writable by the Messenger · Optional**: Whether the Messenger may set it. Options: Yes, No.

### Update

- **Data Attribute ID · Required**: The attribute's id (Get Many lists it).
- **Description · Optional**
- **Options · Optional**: For a text attribute picked from a list: the values, separated by commas.
- **Writable by the Messenger · Optional**: Whether the Messenger may set it. Options: Yes, No.
- **Archived · Optional**: Options: Archived, Active.

### Intercom › Tag

### Get Many

Nothing to fill in.

### Create

- **Name · Required**: The tag's name.

### Delete

- **Tag ID · Required**: The tag's id.

### Intercom › Admin

### Get Many

Nothing to fill in.

### Get

- **Admin ID · Required**: The admin's id.

Source: https://docs.gorunner.io/apps/intercom