API integration for Intercom
We build your Intercom connector
We wire Intercom into your product: the contact is created at signup, chat opens with account context, the ticket carries the business record.
- Senior product team
- support connectors in production
- from scoping to monitoring
What does the Intercom integration do and what changes once client relations are connected?
Intercom is a customer engagement platform combining in-app messaging, chat, email and agent support. Integrating it into your application means opening a conversation or ticket directly from your product with full account context, enriching the Intercom profile with the user's business data, and triggering an automated message when a key event occurs in your product. The support agent sees the client's actual usage without searching in another tool, and the client receives a message at the right moment without the team having to manually decide to send it.
What our clients plug into Intercom
Contact at signup, Messenger open
At signup or plan change, the Intercom record follows. In-app chat talks about the same person as your application.
Onboarding ticket from the form
The onboarding form opens a ticket with business fields. The agent sees product context, not an orphan message.
Incident tracker, linked conversations
A platform incident groups conversations on the same case. Support follows a crisis without losing the thread.
« My requests » portal
The customer follows my requests in your portal. The back office stays out of that mirror.
What this changes in your support
Engineering in service of a measurable outcome: one contact, distinct conversation and ticket, shared product context.
Chat and ticket, each its role
Messenger carries the in-app conversation; the ticket carries the agent case. We do not mix the two: acceptance stays readable.
The EU region is scoped from day one
A European workspace must hit the right entry point. That is the concrete GDPR argument for a French customer.
Support sees context without retyping
Plan, account, incident: the Intercom record follows the product. The agent stops the first-line interrogation.
Notifications stay trustworthy
We verify Intercom event signatures. You act on a real status, not a forgeable message.
How we ship your Intercom connector
Scoping
Private or public app, region, conversations vs tickets, custom attributes (unique names). We list edge cases before writing a line of code.
Development
SHA-1 verify on the raw body, immediate 200, notif_... dedup, contact.id stored on your side. Queue sized for contact / content_stat spikes.
Testing
Conversation vs ticket, irreversible delete, 400 INVALID_PARAMETER on duplicate attribute names, 2,500 tracker links. We replay a 429 webhook you send.
Monitoring
Handler latency, 1,000 errors / 15 min, 429 throttle (1 min → 2 h then drop). You know a flow is broken before your customers do.
What the Intercom API allows
- Contacts
- Users and leads. Upsert from the product, Intercom id stored on your side. Custom attributes: unique names, otherwise PUT conversations returns 400 INVALID_PARAMETER.
- Messenger conversations
- GET/POST /conversations, retrieve (cap 500 most recent parts), reply, tags. Default pagination 20. This is not an agent ticket.
- Inbox tickets
- POST /tickets, POST /tickets/enqueue (async), search, reply, tags, change_type, link/unlink. Delete is irreversible, sensitive data wiped.
- Developer Hub webhooks
- Subscription only in the Hub, tied to the app, all workspaces where it is installed. HTTPS URL, HEAD validation. Versioned topics (ticket.created).
Intercom API vocabulary
- Conversation vs Ticket
- Conversation: Messenger, product real time, 500 parts. Ticket: structured Inbox, types, attributes. POST /conversations does not open an agent ticket.
- X-Hub-Signature
- sha1= + HMAC-SHA1 hex of the JSON, app client_secret (RFC 2104). User-Agent intercom-parrot-service-client/1.0. This is not SHA-256.
- api.eu.intercom.io
- EU host. US: api.intercom.io. AU: api.au.intercom.io. An EU workspace called on the US host is a bug, not an optimisation.
- REST 10-second window
- 10,000 / min / app ⇒ max 1,666 / 10 s. 25,000 / min / workspace. Private apps: workspace apps share the workspace bucket. Headers X-RateLimit-Limit, -Remaining, -Reset.
- Webhook priority < 500 ms
- Response < 500 ms: high queue. Otherwise low queue. Duplicate if no 200 in 5,000 ms. Pause 15 min after 1,000 consecutive HTTP errors / 15 min. Private apps: suspension after 7 days of errors.
- linked_conversation_limit_exceeded
- A tracker ticket cannot link more than 2,500 conversations. Useful for a platform incident, to be scoped before attaching everything.
The real constraints of the Intercom API
Webhooks are subscribed in the Hub
No more subscription API. Tied to the app, notifications from every workspace where it is installed. Old tutorials that POST a subscription are wrong.
Answer fast, or drop events
200 in under 5 s, ideally < 500 ms. A 429 from your side throttles 1 min then 2 h, then drop. In the EU, Intercom can emit 20,000 events / min: your endpoint is often smaller.
Delete is destructive
Delete ticket: irreversible, sensitive data wiped. Delete conversation: retain_metrics true/false, dedicated scope if false. Audit log first, explicit product decision.
Public app: no pasted token
Asking a customer for an Access Token violates the ToS and can get access revoked. Private app: workspace token. OAuth for multi-workspace.
Intercom API or Freshdesk API?
Two support models. Intercom lives in the product (Messenger + Inbox); Freshdesk is a classic ticket helpdesk.
| Criterion | IntercomThis page | FreshdeskTicket helpdesk |
|---|---|---|
| Object | Conversations + Tickets | Helpdesk tickets |
| Channel | In-app Messenger | Email / portal / phone |
| Webhooks | Hub only, SHA-1 X-Hub-Signature | Automations, no dedicated v2 bus |
| Region | api.eu.intercom.io | {domain}.freshdesk.com |
| REST quota | 10,000 / min / app | Plan-based, headers |
| Delete | Irreversible, retain_metrics | Soft + hard_delete |
| The right case | Product with chat + inbox | Classic ticket queue |
The three (Intercom, Freshdesk, Zendesk) are not the same connector. Intercom splits conversation and ticket and signs with SHA-1. Freshdesk bills include. Zendesk requires incremental export. This is a scoping trade-off.
What we measure on an Intercom integration
The other support APIs
If Intercom is not the right foundation, these options are discussed at scoping.
IntercomWe build your Intercom connectorThis page
Freshdeskv2 tickets, contacts, billed include, automations rather than an event bus.
ZendeskTickets vs Requests, Incremental Export, safe_update, HMAC SHA-256 webhooks.We combine Intercom with
The stack around Intercom on our projects.
Intercom integration: your questions
Three steps. First pin the regional host and auth mode: workspace Access Token for a private app, OAuth for a public app (never a token asked of the customer). Then the model: contact.id on your side, Messenger conversations distinct from Inbox tickets, custom attributes with unique names. Finally webhooks in the Developer Hub: verify X-Hub-Signature SHA-1 on the raw body, return 200 immediately, deduplicate on notification id, trust created_at because order is not guaranteed. The hard part is not POST contact, it is the webhook handler and the 2,500 tracker-link cap.
Yes as soon as the workspace is in the EU region. An EU workspace called on api.intercom.io is a configuration bug, not a detail. For a French customer who refuses US routing, the EU host is a concrete GDPR argument, set at scoping, not after the first 4xx. AU: api.au.intercom.io. You do not switch region live without knowing it. Token and host are a pair: mixing them produces opaque 4xx that look like auth bugs.
A conversation is the Messenger thread (in-app), with a 500-part cap on retrieve. A ticket is the Inbox object: types, attributes, agent queue. POST /conversations creates a message initiated by a contact, not a ticket. POST /tickets (or /tickets/enqueue) creates the agent object. A tracker can link up to 2,500 conversations. Delete on either is destructive. Mixing them is the most common UAT error.
A first useful flow, typically contact upsert and a Messenger conversation, ships in two to three weeks. A chain with tickets, portal search, incident tracker and Hub webhooks is closer to six to eight weeks: region, SHA-1 HMAC and handler sizing weigh as much as CRUD. Webhooks are subscribed in the Hub, not via API: that is on the calendar. We scope the perimeter up front and give a firm estimate before starting.
Intercom if support lives in the product (Messenger + Inbox) and the EU region matters. Freshdesk if you want a classic ticket helpdesk, contacts, automations. Zendesk if enterprise support is the system of record, with incremental export and safe_update. SHA-1 at Intercom, SHA-256 at Zendesk, no dedicated bus at Freshdesk: this is not the same connector. Hub subscription instead of an API is the trap in old tutorials.
An Intercom integration project?
Let's talk. 30 minutes to scope contacts, tickets and region, and to tell you frankly what is feasible.
Discuss my Intercom project