Can I build my own Messenger UI using Intercom's API? | Community
Skip to main content
Answered

Can I build my own Messenger UI using Intercom's API?

  • July 2, 2026
  • 3 replies
  • 242 views

Hi intercom,
In order to integrate with other chat service.
We're evaluating the possibility of replacing the Messenger widget with our own chat UI, backed by the conversation API / or intercom-node. 

I found this post before: 

  • You will need to handle apps inserted into the messenger and conversations.
  • You will miss out on a lot of the features offered by Operator.

 

May I know what exactly will miss / break if connecting via API ?
this is what i found so far: 

1. Canvas Kit apps in conversations

2. Fin replies: does Fin's answer arrive as a normal `comment` part (plain text/HTML we can render) ?

3. Read/seen state

Anything else that silently breaks in a custom UI when Operator/Workflows run ?

Or is there a guidance in document regarding this approach?

Thanks

Best answer by Dara K

Hey ​@chihhaohuang 

Yes, it is technically possible to build your own chat UI on top of Intercom APIs, but it is not a drop-in replacement for the Intercom Messenger.

The public Conversations API can create, retrieve, search, update, and reply to conversations, and the conversation model includes conversation parts, custom attributes, linked objects, and AI Agent metadata. So it is a valid API surface for conversation data and basic messaging.

Where it falls short is that the Messenger UI and the Messenger runtime add a lot of behavior on top of those conversation objects. The clearest public guidance we have says that if you build your own UI, you will need to handle apps inserted into the Messenger and conversations yourself, you will miss a lot of Operator functionality, and you will not receive read receipts.

For the specific items you listed:

  • Canvas Kit / Messenger apps in conversations
    Yes — these are one of the biggest gaps. Messenger-specific responses include rich card/app payloads rather than just plain text, and the public guidance is that you would need to handle those app surfaces yourself in a custom UI.

  • Fin replies
    You should not assume a Fin reply will always arrive as a plain text or HTML comment only. In the Messenger response model, Fin and workflow replies can include blocks, sources, reply options, forms, handover CTA/context, carousels, calendar cards, and Fin-specific metadata such as fin_response_type, fin_error_type, and fin_significant_response. In other words, if your custom UI only renders a body string, some Fin and workflow experiences will degrade or break.

  • Read / seen state
    Your understanding is correct that this is another weak point. The public community answer explicitly says a custom UI will not receive read receipts. That matches the implementation behavior: genuine user “seen” updates are emitted through Messenger-specific flows, while programmatic mark-as-read does not generate the same realtime seen signal.

Other things that can silently break or require custom work when Operator / Workflows are involved include quick replies, forms, workflow intro/handover UI, and composer-state behavior. Fin and workflow templates use reply-button, message, Fin, and handoff steps, and the Messenger response model carries reply options, forms, footer notices, and composer state that the stock Messenger knows how to handle.

If your goal is only to make the Intercom entry point feel native in your product, the better-supported approach is to keep the Intercom Messenger and use a custom launcher / JavaScript API to hide the default launcher, open the Messenger from your own button, prefill content, and control visibility.

Or if your goal is to build a fully custom AI chat UI with Fin itself, the more suitable API is the Fin Agent API rather than the generic Conversations API. That API is centered around /fin/start and /fin/reply, and it supports webhook or SSE events such as fin_replied and reply chunks for realtime delivery.

3 replies

Intercom Team
Forum|alt.badge.img+5
  • Dara KIntercom Team
  • Intercom Team
  • Answer
  • July 10, 2026

Hey ​@chihhaohuang 

Yes, it is technically possible to build your own chat UI on top of Intercom APIs, but it is not a drop-in replacement for the Intercom Messenger.

The public Conversations API can create, retrieve, search, update, and reply to conversations, and the conversation model includes conversation parts, custom attributes, linked objects, and AI Agent metadata. So it is a valid API surface for conversation data and basic messaging.

Where it falls short is that the Messenger UI and the Messenger runtime add a lot of behavior on top of those conversation objects. The clearest public guidance we have says that if you build your own UI, you will need to handle apps inserted into the Messenger and conversations yourself, you will miss a lot of Operator functionality, and you will not receive read receipts.

For the specific items you listed:

  • Canvas Kit / Messenger apps in conversations
    Yes — these are one of the biggest gaps. Messenger-specific responses include rich card/app payloads rather than just plain text, and the public guidance is that you would need to handle those app surfaces yourself in a custom UI.

  • Fin replies
    You should not assume a Fin reply will always arrive as a plain text or HTML comment only. In the Messenger response model, Fin and workflow replies can include blocks, sources, reply options, forms, handover CTA/context, carousels, calendar cards, and Fin-specific metadata such as fin_response_type, fin_error_type, and fin_significant_response. In other words, if your custom UI only renders a body string, some Fin and workflow experiences will degrade or break.

  • Read / seen state
    Your understanding is correct that this is another weak point. The public community answer explicitly says a custom UI will not receive read receipts. That matches the implementation behavior: genuine user “seen” updates are emitted through Messenger-specific flows, while programmatic mark-as-read does not generate the same realtime seen signal.

Other things that can silently break or require custom work when Operator / Workflows are involved include quick replies, forms, workflow intro/handover UI, and composer-state behavior. Fin and workflow templates use reply-button, message, Fin, and handoff steps, and the Messenger response model carries reply options, forms, footer notices, and composer state that the stock Messenger knows how to handle.

If your goal is only to make the Intercom entry point feel native in your product, the better-supported approach is to keep the Intercom Messenger and use a custom launcher / JavaScript API to hide the default launcher, open the Messenger from your own button, prefill content, and control visibility.

Or if your goal is to build a fully custom AI chat UI with Fin itself, the more suitable API is the Fin Agent API rather than the generic Conversations API. That API is centered around /fin/start and /fin/reply, and it supports webhook or SSE events such as fin_replied and reply chunks for realtime delivery.

  • chihhaohuang
  • Author
  • New Participant
  • July 14, 2026

​@Dara K thank you for the information. appreciate that!

I would like to followup:

1. Regarding Fin Agent API, can it completely replace conversation API to achieve the same functionalities like messenger widget? more specifically:

1) what happens after the conversation is escalated to human? It seems it still need to use conversation API and I cannot find documentation about this.

2) What’s the relationship between new fin Agent’s conversation and legacy conversation object ? do they share the same API and schema?

It seems that conversation API is still needed in this regard and it seems cover more use cases e.g. no separation between fin and human chat, list conversations…  

Or is there tutorial how to use them together ?

 

2. For mentioned drawbacks, are they solved when using Fin Agent API or will still exist ? 

  • “Canvas Kit / Messenger apps in conversations”
  • “Other things that can silently break or require custom work when Operator / Workflows are involved include quick replies, forms, workflow intro/handover UI, and composer-state behavior.” 

In the end it seems still need to render different types of chat message encoded in html in general ?

Thanks

Intercom Team
Forum|alt.badge.img+5
  • Dara KIntercom Team
  • Intercom Team
  • August 21, 2026

Hey ​@chihhaohuang sorry for the delay in getting back to you!

Thanks for the thoughtful questions. The short answer is that the Fin Agent API does not fully replace the Conversations API or Messenger. It provides programmatic access to Fin, while your application owns the UI and the broader conversation lifecycle.

When you call /fin/escalate, the default behaviour is to create a new Helpdesk conversation with a summary. You can configure an Operator Workflow to route the handoff differently. The response can include an intercom_conversation_id, which you can then use with the Conversations API for Helpdesk operations such as retrieving, listing, assigning, and replying to the human conversation.

The Fin API conversation and the Intercom Conversation object should therefore be treated as related but distinct models. Fin uses your external conversation_id and returns Fin-specific statuses and events; the Conversations API manages the Helpdesk conversation and its conversation parts. There is no documented Fin API endpoint for listing or searching all conversations, so you would normally continue using the Conversations API for that and store the ID mapping.

For the UI, Canvas Kit and Messenger-specific limitations do not apply if you build a completely custom experience. However, your application then needs to implement the equivalent behavior for quick replies, forms, handover screens, composer state, and other interactions. If you use Messenger or Canvas Kit, their existing limitations still apply.

Fin replies do require rendering: the final fin_replied event contains server-rendered HTML in message.body. You can stream the reply first, then replace it with the final HTML when the event arrives. After handoff, conversation parts such as human replies, quick replies, forms, and workflow content may need to be handled separately rather than treated as generic HTML.

Terms & ConditionsAccessibility statement