How to Integrate Retool with Intercom

Before configuring Retool, create an Intercom app to obtain API credentials. Navigate to the Intercom Developer Hub at https://developers.intercom.com and click 'New App'. Fill in your app name (e.g., 'Retool Dashboard') and select the workspace you want to access. After creating the app, you are taken to the app's configuration page. Click on 'Authentication' in the left sidebar. You will see an 'Access Token' section. For the Retool integration, click 'Use Access Token' — this gives you a workspace-scoped token that works immediately without OAuth configuration. Copy the access token. The token provides access to all Intercom API endpoints for your workspace — it is equivalent to a service account with full API access. For production integrations, consider creating a more constrained token by configuring OAuth scopes, but for internal tool dashboards the workspace access token is sufficient. Store the token securely — it does not expire but can be rotated from the Developer Hub if compromised. Note: if your Intercom workspace uses multiple regions, verify the API base URL: EU workspaces use https://api.eu.intercom.io and AU workspaces use https://api.au.intercom.io rather than the default https://api.intercom.io.

In Retool, click the Resources tab in the left sidebar and click Add Resource. Select REST API from the resource type list. Name the resource 'Intercom API'. In the Base URL field, enter the correct base URL for your Intercom workspace region: https://api.intercom.io for US workspaces, https://api.eu.intercom.io for EU workspaces, or https://api.au.intercom.io for Australian workspaces. Scroll to the Authentication section and select Bearer Token from the authentication dropdown. Paste your Intercom access token in the Bearer Token field. Alternatively, add it to Retool Configuration Variables first (Settings → Configuration Variables → Add Variable, name it INTERCOM_ACCESS_TOKEN and mark it as a secret), then reference it as {{ retoolContext.configVars.INTERCOM_ACCESS_TOKEN }} in the Bearer Token field. Scroll to the Headers section and add two default headers that Intercom requires: set Accept to application/json, and set Intercom-Version to 2.10 (or the current API version — check Intercom's developer documentation for the latest stable version). The Intercom-Version header tells the API which version to use; without it, responses may use an older deprecated format. Click Save Changes. The resource is now ready for queries.

Create the foundational queries for the customer support dashboard. In a Retool app, open the Code panel and click + to add a new query. Select your Intercom API resource. Name the first query 'searchConversations'. Intercom provides a powerful search endpoint at /conversations/search — set Method to POST and Path to /conversations/search. The request body contains a 'query' object specifying filter conditions. A basic open conversations query uses: { 'query': { 'operator': 'AND', 'value': [{ 'field': 'state', 'operator': '=', 'value': 'open' }] }, 'pagination': { 'per_page': 25 } }. Bind the filter conditions to UI components (Select for status, Text Input for email search). Create a second query named 'searchContacts' with Method POST, Path /contacts/search. Use a query body that searches by email: { 'query': { 'operator': 'AND', 'value': [{ 'field': 'email', 'operator': '=', 'value': emailSearch.value }] } }. Create a third query named 'getConversationDetail' with Method GET and Path /conversations/{{ conversationsTable.selectedRow.id }}. Add a JavaScript transformer to the searchConversations query that extracts the key fields from the response: id, created_at, updated_at, title (or first message preview), assignee name, state, and tag list.

1// Transformer: normalize Intercom conversations for Table display
2const conversations = data.conversations || [];
3return conversations.map(conv => ({
4  id: conv.id,
5  contact_name: conv.source?.author?.name || conv.contacts?.contacts?.[0]?.name || 'Unknown',
6  contact_email: conv.contacts?.contacts?.[0]?.email || '',
7  subject: conv.title || (conv.source?.body || '').replace(/<[^>]+>/g, '').substring(0, 80),
8  state: conv.state,
9  assignee: conv.assignee?.name || 'Unassigned',
10  team: conv.team_assignee?.name || '',
11  tags: (conv.tags?.tags || []).map(t => t.name).join(', '),
12  created: new Date(conv.created_at * 1000).toLocaleDateString(),
13  updated: new Date(conv.updated_at * 1000).toLocaleDateString(),
14  waiting_since: conv.waiting_since
15    ? Math.floor((Date.now() - conv.waiting_since * 1000) / 3600000) + 'h'
16    : ''
17}));

Assemble the dashboard interface. Drag a Text Input component to the top of the canvas for email search (name it 'emailSearch'). Drag a Button labeled 'Search Customer' that triggers both the searchContacts and searchConversations queries. Below the search bar, create a two-column layout using Container components: left side for the conversation list, right side for customer and conversation detail. In the left Container, drag a Table component and set its Data to {{ searchConversations.data }}. Configure columns: contact_name, subject (truncated), state (as a Tag with color: open=green, closed=grey), assignee, waiting_since. Add a row selection event that triggers the getConversationDetail query. In the right Container, create sub-sections: a Contact Info section showing the contact's name, email, and plan from searchContacts data; a Conversation Detail section showing the full conversation message thread from getConversationDetail; and an Actions panel with three buttons: 'Reply', 'Close Conversation', and 'Apply Tag'. Create a 'replyToConversation' query with Method POST, Path /conversations/{{ conversationsTable.selectedRow.id }}/reply, and a JSON body with type 'admin', message_type 'comment', and body bound to a Multiline Text Input. Create a 'closeConversation' query with Method POST, Path /conversations/{{ conversationsTable.selectedRow.id }}/parts, body type JSON, body { type: 'admin', message_type: 'close' }. Add confirmation modals to destructive actions.

1// Query body: Reply to an Intercom conversation
2// Method: POST
3// Path: /conversations/{{ conversationsTable.selectedRow.id }}/reply
4{
5  "type": "admin",
6  "message_type": "comment",
7  "body": {{ JSON.stringify(replyTextInput.value) }},
8  "admin_id": {{ JSON.stringify(retoolContext.currentUser.email) }}
9}

The most powerful pattern in a Retool-Intercom integration is combining conversation data with internal records. Add a second Resource in Retool — for example, a PostgreSQL database containing your customer records, subscription data, or order history. Create a companion query named 'getCustomerFromDB' that uses the email address from the selected Intercom contact to look up the internal customer record: SELECT c.id, c.plan, c.mrr, c.trial_end, c.created_at, c.account_manager FROM customers c WHERE c.email = '{{ searchContacts.data.data?.[0]?.email }}'. Create additional queries for related data: recent orders, feature usage events, or subscription history. Display these results in the right Container's detail panels below the Intercom conversation thread. Use a JavaScript query named 'buildCustomerProfile' to merge the Intercom contact data with the database record into a unified view: combine Intercom's last_seen, browser, location data with the database's plan, MRR, and account manager fields. Display the merged profile in Statistic components at the top of the detail panel. For complex multi-source customer 360 integrations combining Intercom conversations with Stripe billing data, product usage analytics, and CRM records in a unified view, RapidDev's team can help architect and build your complete Retool support operations platform.

1// JavaScript query: merge Intercom contact with internal DB record
2const intercomContact = searchContacts.data.data?.[0] || {};
3const dbCustomer = getCustomerFromDB.data?.[0] || {};
4
5return {
6  // Intercom fields
7  intercom_id: intercomContact.id,
8  name: intercomContact.name || 'Unknown',
9  email: intercomContact.email || '',
10  last_seen: intercomContact.last_seen_at
11    ? new Date(intercomContact.last_seen_at * 1000).toLocaleDateString()
12    : 'Never',
13  conversation_count: intercomContact.conversation_count || 0,
14  
15  // Internal DB fields
16  plan: dbCustomer.plan || 'Unknown',
17  mrr: dbCustomer.mrr ? '$' + dbCustomer.mrr : 'N/A',
18  account_manager: dbCustomer.account_manager || 'Unassigned',
19  customer_since: dbCustomer.created_at
20    ? new Date(dbCustomer.created_at).toLocaleDateString()
21    : 'Unknown',
22  trial_end: dbCustomer.trial_end
23    ? new Date(dbCustomer.trial_end).toLocaleDateString()
24    : 'N/A'
25};