Intercom

REST API at api.intercom.io with JSON payloads. The Conversation object is central: it contains conversation_parts (messages, assignments, state changes) as a threaded list. Creating a conversation, replying as admin or user, and state transitions (open → snoozed → closed) are clean API operations. The Search API uses structured query objects for filtering contacts and conversations — not string-based search but JSON predicates with operators (=, !=, IN, contains). Pagination uses cursor-based pagination with starting_after and has_more. List endpoints use a scroll API for large datasets. Data attribute management allows custom fields on contacts and companies. Event tracking via the Events API enables behavioral data collection. The API design is consistently modern across endpoints.

API errors return JSON with type, message, and errors[] fields. Error types include not_found, unauthorized, rate_limit_exceeded, and validation_error. Rate limits are generous: 1,000 requests per minute per workspace for most endpoints. Bulk operations (contact imports, tag assignments) are async — agents receive a job object and poll for completion. Webhook delivery retries failed webhooks 5 times with exponential backoff up to 24 hours. The conversation_parts model means agents don't need to worry about message ordering — parts are naturally ordered by created_at. API version deprecation follows a clear lifecycle with advance notice. The main reliability concern: high webhook volume during traffic spikes can overwhelm agent webhook endpoints if not properly queued.

Intercom's API is designed around customer communication rather than traditional ticketing — conversations, not tickets, are the primary object. For agents, this means a richer interaction model: conversations support replies, notes, assignments, snoozing, and closing, with real-time webhook events for each transition. The Contacts API provides user and lead management with custom attributes. Canvas Kit allows agents to build interactive card-based UIs within Intercom conversations — useful for agents that need structured data collection from end users. The Articles API manages help center content. Main considerations: Intercom's pricing is per-seat plus per-resolution, which agents generating high conversation volumes should model carefully. The API surface is modern and well-designed, with GraphQL support for some read operations.

OAuth 2.0 is the recommended auth method for Intercom apps — authorization code flow with scoped permissions. Personal access tokens (generated in developer settings) provide full API access for internal integrations. Access tokens are passed via Bearer header. No fine-grained permission scoping on personal tokens — they grant full read/write access. OAuth scopes provide permission boundaries for marketplace apps. Intercom also supports HMAC-based identity verification for Messenger interactions, preventing user impersonation. Webhook verification uses a signing secret for payload validation. API versioning is header-based (Intercom-Version) which enables controlled migration between API versions — agents should pin their version and upgrade deliberately.

Developer documentation at developers.intercom.com is excellent — well-structured, with interactive API reference, code examples, and conceptual guides. The 'Building with Intercom' section provides architecture guidance for common integration patterns. Canvas Kit documentation includes visual examples of card layouts. Webhook event documentation lists all event types with payload examples. SDKs are available for Ruby, Python, Node, PHP, and Go. The API changelog is detailed and includes migration guides between versions. Intercom's developer community is active. The main strength: documentation is written from an integration developer's perspective, not just an API consumer's — it explains why you'd use specific endpoints, not just how. Sandbox workspaces are available for testing.