Intercom

Intercom uses a workspace access token for server-to-server API calls. This is different from OAuth — you generate it once in the Developer Hub and it remains valid until you regenerate it manually. Log into Intercom and click your workspace icon in the bottom left, then go to Settings. Scroll to the Integrations section and click 'Developer Hub'. If you have not used the Developer Hub before, click 'Build your first app'. Create a new app — name it something like 'Bubble Integration'. You do not need to fill in a redirect URL or set OAuth scopes for a server-side integration. Once the app is created, click on it and go to the Authentication section. You will see a workspace access token — this is a long string starting with 'dG9...' or similar. Click 'Copy' and store it securely. This token gives your Bubble app read and write access to your Intercom workspace data. It does not expire unless you click 'Regenerate' — treat it like a password. Never put it in client-side Bubble JavaScript or a visible field. Note your workspace region before moving on: go to Intercom Settings → Workspace → scroll to find your data region. US workspaces use api.intercom.io, EU workspaces use api.eu.intercom.io, and AU workspaces use api.au.intercom.io. This determines your API Connector base URL.

In your Bubble editor, click the Plugins tab in the left sidebar. If you have not installed API Connector yet, click 'Add plugins', search for 'API Connector', and install the one published by Bubble. It is free. Click on the API Connector in your plugins list and click 'Add another API'. Name this API 'Intercom'. Set the root URL based on your workspace region: - US: https://api.intercom.io - EU: https://api.eu.intercom.io - AU: https://api.au.intercom.io Under 'Shared headers', add the first header: name = Authorization, value = Bearer [paste your token here]. Check the 'Private' checkbox — this keeps the token on Bubble's servers and out of browser network requests. Add a second shared header: name = Intercom-Version, value = 2.10. Do not mark this as Private (it is not a secret). The version header is required by Intercom's API — calls without it either fail or return an older, inconsistent response format that will not match your API Connector configuration. Add a third shared header: Content-Type with value application/json. This is required for POST calls. Save the API root configuration before adding any calls.

1// API Connector — Intercom root configuration
2// US workspace example
3{
4  "API Name": "Intercom",
5  "Root URL": "https://api.intercom.io",
6  "Shared Headers": [
7    {
8      "name": "Authorization",
9      "value": "Bearer dG9rOjxxxxxxxxxxxxxxxxxxxxxxxx",
10      "private": true
11    },
12    {
13      "name": "Intercom-Version",
14      "value": "2.10",
15      "private": false
16    },
17    {
18      "name": "Content-Type",
19      "value": "application/json",
20      "private": false
21    }
22  ]
23}

The most common Bubble-Intercom API call is searching conversations. Intercom uses a POST endpoint for search — not a GET with query parameters — which surprises some founders. In the Intercom API inside the API Connector, click 'Add another call'. Name it 'Search Conversations'. Set the method to POST and the path to /conversations/search. Set 'Use as' to Data — this tells Bubble this call returns data to display, not an action with a side effect. In the Body section, set body type to JSON. The search body uses a query object with field, operator, and value. For a simple 'all open conversations' query, use the body shown in the code block. Click 'Initialize call'. Intercom returns a JSON object with a conversations array — each conversation has an id, title, state, created_at, updated_at, and a contacts section with the contact's name and email. Bubble auto-detects these fields after initialization. In your Bubble editor, create an admin page. Add a Repeating Group element. Set its Type of Content to the Intercom - Search Conversations data source. In the repeating group cells, add Text elements bound to the detected response fields: conversations[i] title, conversations[i] state, and a formatted date from conversations[i] updated_at. Note: Intercom timestamps are Unix timestamps in seconds, not milliseconds. Bubble's date functions expect milliseconds — you may need to handle timestamp formatting in a Backend Workflow or store them as text and display the raw timestamp.

1// POST /conversations/search — request body
2// Returns all open conversations
3{
4  "query": {
5    "field": "state",
6    "operator": "=",
7    "value": "open"
8  },
9  "pagination": {
10    "per_page": 25
11  }
12}
13
14// Response shape (conversations array)
15{
16  "type": "conversation.list",
17  "conversations": [
18    {
19      "id": "1234567890",
20      "title": "Question about billing",
21      "state": "open",
22      "created_at": 1717200000,
23      "updated_at": 1717285600,
24      "contacts": {
25        "contacts": [
26          {
27            "id": "64abc123",
28            "type": "contact",
29            "external_id": "user-001"
30          }
31        ]
32      }
33    }
34  ],
35  "total_count": 42,
36  "pages": {
37    "type": "pages",
38    "page": 1,
39    "per_page": 25,
40    "total_pages": 2
41  }
42}

A common pattern is creating or updating Intercom contacts when users sign up or update their profile in Bubble. Intercom's API uses a POST /contacts endpoint that creates a contact if the email does not exist, or updates the existing contact if it does — effectively an upsert. In the API Connector, add another call to the Intercom API. Name it 'Upsert Contact'. Set the method to POST and the path to /contacts. Set 'Use as' to Action. In the Body section, use JSON body type with the contact fields you want to sync: email (required), name, phone, external_id (your Bubble User's unique ID), and custom_attributes (an object for any extra fields). Using external_id as your Bubble User ID is important — it lets you look up Intercom contacts by your Bubble user ID later without needing to store the Intercom contact ID. For Initialize call, use a real email address you own. Intercom returns the full contact object including its Intercom-assigned id field. Store this id in a Bubble database field on the User record so you can reference the Intercom contact in future API calls without another lookup. To wire this to user signup: in the Workflow editor, create a workflow triggered by 'When a User signs up'. Add the action Plugins → Intercom - Upsert Contact. Map Current User's Email to the email parameter, Current User's Name to name, and Current User's unique ID to external_id.

1// POST /contacts — upsert contact body
2{
3  "email": "<user_email>",
4  "name": "<user_name>",
5  "phone": "<user_phone>",
6  "external_id": "<bubble_user_id>",
7  "custom_attributes": {
8    "plan": "<user_plan>",
9    "signup_date": "<signup_date>"
10  }
11}
12
13// Response includes Intercom contact ID to store
14{
15  "type": "contact",
16  "id": "64abc123def456",
17  "email": "user@example.com",
18  "name": "Jane Smith",
19  "external_id": "bubble-user-001",
20  "created_at": 1717200000,
21  "updated_at": 1717200000
22}

Intercom can send webhook events to your Bubble app when things happen in Intercom — a conversation is closed, a new lead is created, a user attribute changes. This requires a Bubble Backend Workflow exposed as an API endpoint. Backend Workflows require a paid Bubble plan (Starter or above — not available on free). RapidDev's team has built hundreds of Bubble apps with webhook integrations like this — if you want help structuring the event processing logic, book a free scoping call at rapidevelopers.com/contact. To set up the endpoint: go to Bubble's backend workflows section (in the Workflow editor, switch to the Backend tab). Create a new API Workflow. Name it 'Intercom Webhook'. Check 'This workflow can be run without authentication' — Intercom cannot send your Bubble auth token, so the endpoint must be publicly accessible. Click 'Detect request data'. Intercom sends a JSON POST payload — click 'Detect data' and go to Intercom's Developer Hub to send a test event to the URL shown. Alternatively, paste a sample Intercom webhook payload manually. Bubble will detect the field types from the payload. Map the fields you need: type (the event name), data > item > id, data > item > state, data > item > contacts. Add workflow steps after detection: create or modify a Bubble database record based on the event type. Add a 'Return data from API' step at the end that returns {} with a 200 status — Intercom expects a 200 response within 5 seconds and will retry the webhook if it times out. In Intercom's Developer Hub, go to your app → Webhooks. Add the Bubble API endpoint URL as a webhook URL. Select the topics you want: conversation.closed, conversation.created, contact.created, etc. Save and send a test event to verify the connection. Note: The Backend Workflow URL shown in Bubble has an /initialize suffix for the schema detection step. Drop the /initialize suffix when registering the production webhook URL in Intercom — the production endpoint is the URL without /initialize.

1// Intercom webhook payload example (conversation.closed)
2{
3  "type": "notification_event",
4  "app_id": "abc123",
5  "data": {
6    "type": "notification_event_data",
7    "item": {
8      "type": "conversation",
9      "id": "1234567890",
10      "state": "closed",
11      "title": "Question about billing",
12      "created_at": 1717200000,
13      "updated_at": 1717285600,
14      "contacts": {
15        "contacts": [
16          {
17            "id": "64abc123",
18            "external_id": "bubble-user-001"
19          }
20        ]
21      }
22    }
23  },
24  "delivery_attempts": 1,
25  "delivered_at": 0,
26  "first_sent_at": 1717285600,
27  "notified_at": 1717285600,
28  "created_at": 1717285600
29}