Intercom integration

Overview

Intercom is a customer-messaging platform for support, in-app chat, and lifecycle marketing. The Automize Intercom connector covers contacts (the unified user model), conversations, messages, companies, tags, segments, and notes.

• Regions: Intercom uses regional data hosting (US, EU, AU). The API endpoint differs per region (api.intercom.io for US, api.eu.intercom.io for EU, api.au.intercom.io for AU). Connector picks the right endpoint from your account's region setting.
• Plans: Essential, Advanced, Expert – all expose the API. Some endpoints (custom data attributes, advanced segments) need Advanced or above.

Setting up the connection

Auth type: Bearer Token.

1. Sign in to app.intercom.com → Settings → Integrations → Developer Hub.
2. Create a new app. Set scopes (read users, write users, read conversations, write conversations, etc.).
3. Generate an Access Token (long alphanumeric). For your own workspace this works immediately.
4. For OAuth (multi-customer apps), set the Redirect URI and use the Client ID + Secret.
5. In Automize, open Settings → Connectors → Intercom → Add connection. Paste the access token, choose region.

Find your credentials at https://app.intercom.com/a/apps/_/developer-hub.

Rate limits

Intercom enforces 1,000 requests/min/app for Standard endpoints, lower for resource-intensive ones (~83/10s for searches). The connector retries 429 with the Retry-After header.

Data model

Intercom's data model has merged 'users' (logged-in customers) and
'leads' (anonymous prospects) into the unified Contact model.

    Contact (role: user or lead) ─┬─ Conversations ─── Conversation Parts (messages)
                                  ├─ Tags
                                  ├─ Notes
                                  └─ Company (membership)
    Company ─┬─ Members (Contacts)
             ├─ Tags
             └─ Custom attributes
    Segments (dynamic queries over Contacts)

Available operations

18 operations available. Click any row to jump to its detail.

Operations

Close Conversation

Close a conversation

Tips

• Closes the conversation. Customer can re-open by replying.

Create Contact

Create a contact (lead or user)

Tips

• role: 'user' (logged-in customer with external_id) or 'lead' (anonymous prospect).
• email + name + custom_attributes.

Errors

• Already exists – Contact with this email + role already exists. Use Search Contacts then Update.

Send Message

Send a message to a contact

Create note

Create a note on an Intercom contact.

Delete contact

Delete an Intercom contact.

Get Contact

Get contact details

Tips

• Use contact_id (internal Intercom ID), email (with role filter), or external_id (your own ID).

Get Conversation

Get conversation details

Tips

• Returns full conversation thread + all parts (messages).

List Admins

List all admins

No input parameters.

Tips

• Teammates (your agents). admin_id is what you pass to Assign Conversation.

List Articles

List help center articles

No input parameters.

List Companies

List all companies

No input parameters.

Tips

• Returns companies. Filter via Search Companies.

List Contacts

List all contacts

No input parameters.

Tips

• Returns contacts (both users + leads). Filter via Search Contacts for typed queries.
• Pages via starting_after cursor.

List Conversations

List all conversations

No input parameters.

Tips

• Returns conversations. Use Search Conversations for filtered queries.

List segments

List Intercom segments.

No input parameters.

Tips

• Returns dynamic segments. To get the contacts in a segment, query Contacts with segment_id.

List tags

List Intercom tags.

No input parameters.

Tips

• All tags in the workspace.

Reply to Conversation

Reply to a conversation

Tips

• type: 'admin' (agent reply) or 'user' (customer reply, requires intercom_user_id or user_id).
• body: HTML or text. message_type: comment (regular reply) or note (internal-only).

Search contacts

Search Intercom contacts.

Tips

• Operator-based query: {query:{operator:'AND', value:[{field:'email', operator:'=', value:'foo@bar.com'}]}}.
• Slower than direct ID lookups – use Get Contact when you have an ID.

Tag contact

Add a tag to an Intercom contact.

Tips

• Add or remove a tag from a contact. Used heavily for segment building.

Update contact

Update an Intercom contact.

Tips

• PUT-style. custom_attributes are merged in (additive).

FAQ

Lead vs User – what's the difference?

Lead = anonymous prospect (no external_id, identified by browser/cookie). User = logged-in customer with an external_id from your app. A Lead can be merged into a User when they sign up – preserves conversation history.

external_id vs Intercom ID – which to use?

external_id is your own identifier (your database user.id). Stable across Intercom data migrations. Intercom ID is internal – fine for short-term lookups but tie your records to external_id for the long term.

Regional data – how do I know my region?

Settings → Workspace → Region. Don't guess – wrong region = 401 / 404 on every call. The connector lets you pick the region on the connection settings.

Custom attributes – how do I add new ones?

Create them in Intercom's UI first (Settings → Data → Custom Attributes), then send them in custom_attributes on create/update. Sending an undefined attribute is silently ignored.

Why is Reply Conversation creating a new conversation?

If you passed conversation_id incorrectly or the conversation is closed AND you replied as a user, Intercom may spawn a new conversation. Verify the conversation is open and the ID is right.

Related connectors

• Zendesk
• Freshdesk