Connecting Voice Agents to Intercom

Intercom is the messaging-first customer communication platform that a lot of SaaS companies run their support on. Historically chat-centric, it's expanded to cover email, a light voice layer, and AI-native tools (Fin). For voice AI deployments where the main customer support conversation happens in Intercom, your voice agent needs to read Intercom context, write conversations and notes, and route cleanly to Intercom-using teammates. This piece walks through the Intercom-specific integration patterns.

TL;DR

• Intercom's API is clean, REST-based, well-documented.
• OAuth 2.0 for Marketplace apps; API tokens for internal integrations.
• Core objects: Contacts, Conversations, Companies, Notes.
• Voice calls typically become Conversations with attached notes or as separate Contact interactions.
• Fin (Intercom's AI) and voice AI can complement each other; plan the handoff.

What Intercom is good at

Intercom's strengths:

• Unified inbox — chat, email, voice, and AI all in one thread per customer.
• Lightweight data model — Contacts, Conversations, Companies.
• Fin AI — Intercom's native AI assistant for chat.
• Messenger widget — embedded in the customer product.
• Product-centric — designed for SaaS and digital-first businesses.

Voice AI integrates naturally because Intercom's data model already thinks in terms of ongoing customer conversations.

Authentication

Private App / Access Token. For internal integrations. Create in Intercom Settings → Developers → New App. Generate an access token.

OAuth 2.0. For Marketplace apps shipped to multiple customers.

Use a Private App with narrowly scoped permissions for most voice AI integrations.

The REST API basics

Base URL: https://api.intercom.io/

Key endpoints:

• GET /contacts/{id} — read a contact.
• POST /contacts — create a contact.
• PUT /contacts/{id} — update a contact.
• POST /contacts/search — search contacts.
• GET /conversations/{id} — read a conversation.
• POST /conversations — create a conversation.
• POST /conversations/{id}/reply — add to conversation.
• POST /conversations/{id}/parts — add a note or action.

API version: use Intercom-Version header. Pin to a specific version and upgrade deliberately.

Lookup by phone number

Intercom contacts have phone in phone field:

POST /contacts/search
{
  "query": {
    "field": "phone",
    "operator": "=",
    "value": "+15551234567"
  }
}

Note: phone is sometimes sparse in Intercom (Contacts often come in via email/chat). If no phone match, try the email if the caller provides one.

Creating a conversation from a call

POST /conversations
{
  "from": {
    "type": "contact",
    "id": "{ContactId}"
  },
  "body": "AI voice agent call summary:\n\n{Summary}\n\nTranscript:\n{Transcript}"
}

The body is what's visible in the inbox. Structure it so human teammates can scan quickly.

Adding notes (internal) to existing conversations

If the caller has an ongoing conversation:

POST /conversations/{id}/parts
{
  "message_type": "note",
  "body": "Voice AI called follow-up at 14:23. Caller confirmed issue resolved.",
  "admin_id": "{AdminId}"
}

Notes are internal and don't notify the customer.

Replying to customer (public) from voice AI

If the voice AI is handling the conversation end-to-end and the next step is a reply:

POST /conversations/{id}/reply
{
  "message_type": "comment",
  "type": "admin",
  "admin_id": "{AdminId}",
  "body": "Hi Jamie — as we discussed on the call, I've filed the ticket for the tier-2 team. They'll reach out by end of day."
}

This actually sends to the customer. Use sparingly.

Custom attributes

Intercom contacts and companies can have custom attributes. Voice AI can populate:

• Last call date.
• Call outcome category.
• Escalation flag.
• NPS signal.

Coordinate with the Intercom admin on which custom attributes to use or create.

Tagging

Intercom supports tags on conversations and contacts:

POST /conversations/{id}/tags
{
  "id": "{TagId}",
  "admin_id": "{AdminId}"
}

Tags like voice-ai, escalation, qualified-lead drive routing and reporting.

Team inbox routing

Intercom's team inboxes are how different teams see their conversations. Route by:

• Assigning to a specific team.
• Assigning to a specific admin.
• Using Rules/Operators to auto-route on create.

Setup is a dance with the Intercom admin. Voice AI provides hints (tags, custom attributes); Intercom's Rules act on them.

Fin AI integration

Intercom's Fin AI handles chat. When your voice agent hands off to Intercom:

• Fin may already be engaged in chat with the same customer.
• Your voice agent's conversation can share the Fin context.
• Fin can take over the follow-up.

This is an evolving area — check current Intercom capabilities. The design intent is multi-channel AI orchestration.

Webhooks

Intercom fires webhooks on events:

• Conversation created, replied, closed.
• Contact created, updated.
• Custom attribute changed.

Useful for triggering outbound voice agent calls in response to Intercom events.

Messenger-triggered calls

A modern pattern: customer is in an Intercom chat, escalates to "can we talk?" → voice agent call initiated from within the Messenger experience. Requires Intercom SDK integration and voice AI handling the inbound.

Companies

Intercom Companies group contacts by organization. For B2B SaaS deployments, surface Company context in the voice call:

• Account tier, MRR, expansion history.
• Assigned CSM.
• Recent health signals.

Rate limits

Intercom rate limits:

• Standard: 1000 API calls/minute per app.
• Higher on enterprise plans.
• 429 responses on exceedance.

Implement retry with backoff.

Common pitfalls

Admin identity confusion. Every conversation action requires an "admin" performing it. Create a dedicated "Voice AI" admin in Intercom so actions are clearly labeled.

Chat vs voice semantics. Intercom is chat-first. Voice agent conversations in the Intercom inbox can feel odd without clear visual markers (tags, icons).

Public reply accidents. Posting a note as a public reply sends to the customer. Double-check message_type.

Contact deduplication. Same person appears as multiple contacts (different emails, phones). Intercom's merge feature addresses this; plan for it.

Custom attribute sprawl. Add voice-AI-specific attributes thoughtfully. Coordinate with admin.

Example end-to-end flow

# Inbound call
1. Voice AI receives call, extracts phone number.
2. Middleware → Intercom search for contact by phone.
3. If found: load recent conversations, open tickets, company context.
4. If not found: create contact, get ID.
5. Voice AI handles conversation with context.
6. Call ends.
7. Voice AI → Middleware: create conversation in Intercom with transcript.
8. Apply tags (voice-ai, call-category).
9. Update contact custom attributes (last call date, outcome).
10. If escalation, assign to appropriate team.

Integration architecture

Voice agent → middleware service → Intercom API.

Middleware:

• Manages auth and token refresh.
• Normalizes data between voice agent events and Intercom format.
• Handles rate limits and retries.
• Manages "Voice AI" admin identity.
• Logs errors to observability.

Testing

• Intercom workspace sandbox — free test environments.
• Test contacts seeded with realistic data.
• Scope permissions per least-privilege.
• Exercise error paths — rate limits, auth, contact collisions.

Related reading

• Twilio + Voice Agents: A Complete Guide
• Sending Voice Agent Transcripts to Slack
• Connecting Voice Agents to Snowflake or BigQuery
• How to Port a Phone Number to Your Voice Agent
• Setting Up Toll-Free Verification for AI Calling

FAQ

Can voice AI engage with Fin mid-call? Not directly. But voice AI handoff can land in an Intercom inbox where Fin continues via chat later.

What about Intercom Phone? Intercom's native voice product. Voice AI integrations can route to/from Phone if configured.

Can we use Intercom as the knowledge base for voice AI? Yes — Intercom Articles can serve as the KB. Query via Intercom API or a dedicated KB integration.

What about Intercom Pulse (analytics)? Pulse shows conversation metrics; voice AI interactions appear in the same dashboards if tagged correctly.

How do we handle multi-workspace customers? Per-workspace access tokens and integration configs. Each workspace is isolated.