API & Webhooks

We want to add a note to an Intercom conversation but without impersonating an existing admin user. The API docs suggest that to reply with a note, you need:message_type: note type: admin an admin_idWe’re triggering this from within our app and, under certain conditions, want to programmatically append additional context as an internal note. If there’s another way to attach context to a conversation, that could also work.Ideally, we’d post on behalf of a bot or app, but I can’t find anything in the docs that supports this. Impersonating a user feels like a security risk, and creating a dedicated seat for this purpose introduces its own concerns.Is there a recommended pattern for handling this?

Hello, according to FIN there is no way to merge conversation besides using the UI. Can you confirm if this is true? Merging conversations via api is a crucial part of our workflow. 

Hey everyone We're pulling Intercom data via webhooks into BigQuery for reporting. We need agent roles and job titles, but we're not seeing these fields in any webhook payloads (e.g., conversation events).Before building a separate pipeline to poll the Admins API daily, wanted to ask:Is there a webhook topic that includes admin metadata like role and job_title? If not — how are others keeping admin details in sync? Just polling the API on a schedule?Would love to hear how you've approached this.Thanks!

The v2.13 REST API introduces support for creating, updating, and reading custom object instances. But, the documentation does not say anything about updating references – either on those instances themselves, or references to custom objects as custom attributes on people.Without the ability to associate custom objects with contacts or conversations, the API doesn’t seem very useful.I’ve tried to pass contact IDs and external IDs, and objects with an “id” key with no success, both as arrays and as simple attributes. Based on how the contacts/{id}/companies endpoint works, I’d probably expect the following to work:POST /custom_object_instancesContent-Type: application/json{"external_id": "123", "custom_attributes": {"Owner":{"id":"6602eae0ca854b5e2a01f503"}}And if the attribute support multiple people, it should support an array. Supporting objects, instead of just the ID, would allow you to support identifying references with both Intercom’s ID and external ID, so that’d be nice.I’ll n

Hi,Recently I have been noticing that we have been receiving an error_code of “not_found” when making a POST request to the /contacts endpoint (creating a contact).This is surprising as I am not sure how this is possible when creating a contact (as opposed to updating one).If it helps, an example request id for this 000bkte0pcsrns5hpus0, hopefully I am not just off-base but I was looking to understand how this might happen? I am not sure what this error code could mean when trying to create a contact.

Hi Intercom Support/Community,We want Fin to trigger an OTP verification flow whenever a customer asks for personal information, before Fin is allowed to call our backend and retrieve sensitive data. What we have today (custom SMS OTP via our backend): Data Connector – Generate OTP: calls our backend, and the user receives a code via SMS. Data Connector – Verify OTP: Fin should ask the user for the code, send it to our backend for verification, and then our backend returns a token. After verification, we want Fin to use that token to access backend information via subsequent calls We tried implementing this via Fin Tasks, but it’s not working well for us.Question: What is the most effective/supported way in Intercom to implement this flow end-to-end (SMS OTP + verification + then allow sensitive Data Connector calls)?

When retrieving a conversation via the REST API  GET /conversations/{id}, the initial message that starts a side conversation is not included in the response. Only subsequent replies appear as part_type: "side_conversation_reply" or part_type: "side_conversation_started" as a conversation_part under the  conversation_parts section.Observed behavior: The originating message (e.g., "Hi team, please answer clients query below...") sent by an admin to start the side conversation is completely missing. This message doesn’t appears neither in the api response nor in the main conversation thread in the intercom website, but when we click View side conversation in the main conversation thread in intercom, we can view all the side conversations opened in a separate dialog box.We want to ingest all side conversations related to a conversationId, Is there any endpoint provided by intercom to ingest them? or any other possible way?

How can I search a ticket using the ticket_id with the rest API? It looks like we can only search with id, not ticket_id.

Hello there! I am having some issues to understand how to assign the Conversation Rating to an agent. Context: I am using Fivetran connector to load the data on our Data Warehouse and from conversation_history table I am grabbing the column conversation_rating_teammate_id to link the owner of the rating with the corresponding admin/agent. Issue: We want to attribute the rating of each conversation to an agent using the same logic Intercom is using in the UI where the last agent who respond get the credit but for some conversations the last message author ID from conversation_part_history is not the same as the conversation_rating_teammate_id. Can someone explain me how this attribution logic works?Thanks!

I added some custom attributes like lead_id and lead_email.I tried to send those under custom_attributes or directly. Both failed. intercom.boot({ ...additionalSettings, .lead_id: visitorId, lead_email: email,}); intercom.boot({ ...additionalSettings, custom_attributes: {lead_id: visitorId, lead_email: email},});I expect to see those in contact.merged or contact.user.created or contact.user.updated Webhooks but could not.

I'm trying to get the user ID in order to make additional API calls, but I can't get it other than by performing an additional API call to look up the user's email address, which seems like a rather roundabout way of doing it?

We are trying to use official @intercom/messenger-js-sdk with our react app.https://www.npmjs.com/package/@intercom/messenger-js-sdkWe are calling Intercom instance in our App component Intercom({ app_id: ..., });and then updating user info when user data is available using following functions:import { boot, shutdown, update } from "@intercom/messenger-js-sdk"; when there is no user data we are calling boot with only id,boot({    "app_id": "...",})and if there is user data, we are passing required properties to boot functionboot({    "app_id": "...",    "user_id": "...",    "name": "...",    "email": "...@......",    "created_at": ....,}) It seems that when calling with boot({ "app_id": "..."}), user data is not cleared and in chat we continue to receive messages as if user is still logged in.Once boot() is called with user data, can it be rebooted with no data (for example, in scenario if user is logged out from our app and we want new chat instance without user data)? Also, if t

The Companies List API has a limit of 10000 companies. Does the Retrieve API have the same limits?In other words, can I call https://api.intercom.io/companies?page=<page>&per_page=50 and paginate over more than 10000 companies?

I’m trying to pull a list of the most recently updated articles in Intercom. In all of the documentation it says that the data is by default coming in as descending of Updated At. However, from my limited knowledge and use of Zapier and Postman’s AI bots, it seems the data is coming in with a sort of Created Date and not Updated Date. Anyone else notice this?Thanks

In order to know, which languages are available in Intercom I am used to going toThe list: https://developers.intercom.com/docs/references/rest-api/api.intercom.io/articles/article#path=translated_contentAnd by extracting the translated_content[language] I get a list of all the language codes possible. I am using this to validate our internal list of languages we use! But what if Intercom ever adds a new language? Is there an endpoint I could use to fetch the available languages?

When fetching conversations via the Conversations API (GET /conversations/{id}), I’ve noticed a difference between WhatsApp images and WhatsApp audio messages. Image messages include full attachments data (URL, content_type, filesize, etc.). Audio messages, however, show attachments: [], even though the Intercom Inbox UI displays an audio clip. The only extra field is external_id with a WhatsApp wamid, but no file URL or metadata. Example audio part:{ "part_type": "comment", "body": "<p>Sent an audio clip</p>", "attachments": [], "external_id": "whatsapp:wamid...." } How can this be resolved?

I would like to connect Intecom to MS co-pilot via an MCP server. MS co-pilot is the only LLM we are allowed to work with at our company. I want to use co-pilot to analyse our conversations and make custom reports I can't make in the reports section. Ive seen the integration → data connector section, but that seems to be the other way around, get data from another system to use in intercom, but I want to use the data in intercom in co-pilot. Anyone can help me here? During the community hour the said this was possible. 

Hello everyone,I’m Darshan Hiranandani, I’ve been working on an API that allows me to create articles with titles and main content. So far, I’ve been able to create articles successfully, but I’m facing a challenge when it comes to uploading images or attachments to these articles.I know some platforms like Intercom have hosting services that allow you to upload and store attachments, but I’m not sure if they offer something similar for direct image uploads.Can anyone share their experience or suggestions on how to upload images or attachments via REST API? Any help or ideas on how to handle this would be greatly appreciated!Thanks in advance!RegardsDarshan Hiranandani

Hello everyone,I’m Darshan Hiranandani, working on an application that has thousands of users, and I need to regularly create and update these users in Intercom, at least once a week. The problem is that the current Contacts API doesn't fully support bulk updates and comes with some significant limitations:It requires my app to track whether a contact already exists before performing a POST or PUT request. The API rate limits are very restrictive, especially for medium-sized user bases (166 requests per 10 seconds). It also requires storing the Intercom ID for updates, which isn’t ideal since my app uses an external ID for users. Additionally, the manual import process requires mapping each attribute, which is cumbersome and prone to errors.Given these constraints, I’m looking for a better approach or solution to enable bulk creation and updating of users in Intercom. Has anyone worked around these issues or found a better solution for handling bulk user operations?Would love to hear y

Hi there! We’re using the JavaScript implementation for web as followed on the docs, and we have some users reporting that they are either seeing a semi-colon added on the upper-right corner of the screen, or a full side panel that’s being injected when the “Need help?” badge is being shown. Please see the attached photos for a visual reference.Is this a bug that you are already on track or have a fix for? We’ve tried trying this to a simple page without any components, but it doesn’t seem to fix the issue. Any intel on this would be very helpful. Thanks!  

Hi all, I am working on a feature attempting to automate the creation of few contacts in our workspace by hitting the post endpoint for `{intercom_api_url}/contacts`.My current data body looks like:{ email: providerData.providerEmail, name: providerData.providerName, phone: providerData.providerPhoneNumber, // These custom attributes throw an error in intercom when added. custom_attributes: { Is_provider: true, // provider_start_date: new Date().toDateString(), }, }Although the Is_provider custom attribute exists in the test workspace, my call keeps throwing me a 400 error with Bad Request.Please help with understanding why this is happening and if possible a potential fix. This would allow us to onboard a lot more contacts very quickly.

Hi,I am trying to use Custom Objects to show the orders of a users that message us, either through email or whatsapp. I created the custom object Order with the relevant attributes. I then created an external reference in People and Conversations, referencing Order via a one to many relationship. Then I created a webhook that triggers when a conversation is created or a reply is given. The webhook calls a service that posts to /custom_object_instances/OrderWe post an external_id and custom_attributes according to https://developers.intercom.com/docs/references/rest-api/api.intercom.io/custom-object-instances/createcustomobjectinstances -d '{ "external_id": "123", "external_created_at": 1392036272, "external_updated_at": 1392036272, "custom_attributes": { "order_number": "ORDER-12345", "total_amount": 99.99 }Now the documentation does not say anything about how to link the Order to People.Fin says, you need to put a customer property inside custom_attributes, fi

We’re Intercom customers and we need to build a variation of the checklist on our own page, not inside the Messenger widget. I assumed the most obvious solution would be to consume an API that returns these checklists, similar to how it works with articles. Do we have anything like that? I couldn’t find it in the documentation.This is very important for us!

👋 Hi everyone! Karla here from the Technical Support Engineering team. Today, we’re diving into how to use Custom Actions and Custom Objects to reference People data — the kind of data that sticks with your users across multiple conversations. We’ll walk through setting up a Prescription Tracker workflow — a simple example that shows how to store and display data for each user inside Intercom Messenger. Let’s start with the why. Imagine you’re tracking prescriptions for your customers. If a user chats today about Tylenol, you’d want that stored on their profile. Then, if they return next week about Ibuprofen, that data should build on top of their record — not replace it. That’s what People data does: it acts like a long-term memory for your users. Each conversation can reference one item (the chat about Tylenol, for example), but the People record holds the full history of every prescription that’s ever been added for that user. Let’s start by checking out what my test API returns wh

We are experiencing a critical issue with Intercom integration in our web application.After a user logs in without a full page reload, the Intercom widget appears and lists existing conversations. However:- Existing conversations cannot be opened- Creating a new message often fails- Network tab shows intermittent 403 Forbidden errors with the message: “App suspended”- - Specifically on requests to: POST /messenger/web/conversations/:idIf the user reloads the page after login, everything works as expected:- Conversations open normally- New messages are sent successfullyContext:- We are using the react-use-intercom package for frontend integration.- The app performs a soft reboot after login (without reloading the browser tab). Call shutdown and boot with intercomUserJwt then- When I had this issue it was always because the app_id passed was 'undefined'We are unsure whether this issue originates from the `react-use-intercom` package or from Intercom itself.If you have any suggestions on