Skip to main content

API & Webhooks

Get more out of Intercom using our API and webhooks

  • 529 Topics
  • 1,201 Replies
528 Topics
A
Achaias HaycockNew Participant
posted in API & Webhooks
Python SHA-1 webhook verification

I want to make this post as I have spent the last day trying to understand why the X-Hub-Signature being sent in the header wasn’t matching the the HMAC signature that I was getting when converting the JSON body and Client Secret from the request.If you are using Python, MAKE SURE YOU USE SEPARATORS IN THE JSON DUMP BEFORE ENCODING. Here is the method that worked for me: def authenticate_intercom_request(self,x_hub_sig): json_string = json.dumps(self.body, separators=(',', ':')) hashed = hmac.new(self.secret.encode('utf-8'), json_string.encode('utf-8'), sha1) return hmac.compare_digest(hashed.hexdigest(), x_hub_sig[5:])Python by default will add chars in the body that will alter the returned value from Intercom, and without the separators listed above it will always fail. 

441
Paul Byrne
Intercom Team
M
MindyNew Participant
asked in API & Webhooks
Has anyone successfully used a third party for a workaround to use OpenID for SSO?

My team has run into a roadblock in setting up single sign on for our platform. We use OpenID, and it’s not configurable natively in Intercom. I’ve found some articles stating that some third party partners offer a ‘go between’ workaround for this, but I’d love to hear from the community if anyone has successfully set this up and what the experience was like with the third party they chose.

92
Paul Byrne
Intercom Team
C
cooldevNew Participant
asked in API & Webhooks
Getting 404, 502 and 504 error from API at the first time then success after retry

My context:API version: 2.12API call: search and update contact404 Curl request at 2025-03-31 09:50:33 { "headers": { "content-length": "74", "user-agent": "GuzzleHttp/7", "host": "api.intercom.io", "authorization": "********", "accept": "application/json", "content-type": "application/json" }, "body": "{\"query\":{\"field\":\"external_id\",\"operator\":\"=\",\"value\":\"vegastars_78859\"}}", "url": "https://api.intercom.io/contacts/search", "method": "POST"}Here is the response at 2025-03-31 09:50:33:I have double-checked that the value exists in Intercom. However, the weird thing is that when my server calls the API, it returns an error response. Then, when the request is retried by the queue, it succeeds.I want to make sure that are these response such as 404 and 502, 504 coming from your side ?{ "body": "<html><head><title>404 Not Found</title></head><body><center><h1>404 Not Found</h1></center><

422
mateusz.leszkiewicz
Intercom Team
P
Paula ShulerNew Participant
asked in API & Webhooks
How to export Intercom ID for all contacts?

I would like to export the Intercom ID of all users - and the only documentation I can find is to do this via API. I am using Postman for this but I was hoping to find a way to get it as a CSV or something easier to navigate. Can anyone point me in the right direction to get this data?

2702
TBelevska
L
Laura AllahverdiNew Participant
asked in API & Webhooks
Need to hire API expert for export/import

Hi, I need someone who can export all my past conversations in Intercom and add them to the appropriate “notes” sections of my contacts in Hubspot.  

402
TBelevska
I
Ian LNew Participant
posted in API & Webhooks
Migrating Zendesk Tickets to Intercom

Hey there!We’re about to run a script on our side this week to migrate our historical Zendesk Ticket data to Intercom.Has anyone in the community had experience doing this?Curious to know how you prevent email notifications from going out to customers, and if its possible to backdate the conversations when you are creating them.Cheers,Ian

2653
TBelevska
J
John SeoNew Participant
asked in API & Webhooks
User attributes missing in Intercom (Name and Email) for recently created users

Hi, I need your help with user data not showing correctly in Intercom.We are initializing Intercom with name, user_id, email, and user_hash.Everything works fine for most users, but starting from 3 weeks ago, new users only show user_id, and name and email are missing on their profiles.At first, we suspected it might be an issue on our end. However, we’re also sending the exact same user data to Pendo, and it’s working perfectly there — all fields are showing as expected.Could you help us check if there were any changes on Intercom's side, or suggest what else we can verify to resolve this?Thanks!

220
J
S
SmockNew Participant
asked in API & Webhooks
Getting "User Not Found" error when creating a contact

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.

5585
S
A
Alex D.New Participant
asked in API & Webhooks
Exporting articles - how do you actually export them using the API?

HiI know that I need to use the API to export articles, and I’ve looked at a couple of existing questions around this. The answer seems to be, you need to use the API and to look at the article Formatting and exporting your articles with the API for answers. That article doesn’t have any information about exporting articles using the API. It has one line of text right at the bottom, pointing you to the developer docs, but not guidelines as to how to start.  I looked at the data export section of the developer docs and gave that a try, and first of all found out that it will only pull data from a 90 day period, so pretty useless if you want to export docs that have been created over time. I tried the Export API endpoint with a shorter time period and still had issues. For anyone else trying, you first have to Create a Data export, the response from that request will give you a job number. You then need to download the data export, using the job number.I tried this in the Intercom test e

772
TBelevska
H
HugoNew Participant
asked in API & Webhooks
Using Intercom's API to calculate common conversation metrics

I have been using the Intercom API to try to recreate the regular metrics in Metabase. I have tried using this resource but haven’t found it to be particularly helpful. For example, if I try this query, the response maps to the New Conversations Metric in the Intercom dashboard instead of the Assigned Conversations metric which is my intention. SELECT  "Inbox Details - Team Assignee"."inbox_name" AS "Inbox Details - Team Assignee__inbox_name",  COUNT(*) AS "count"FROM  "public"."conversations_data" LEFT JOIN "public"."inbox_details" AS "Inbox Details - Team Assignee" ON "public"."conversations_data"."team_assignee_id" = "Inbox Details - Team Assignee"."inbox_id"WHERE  (    (      "Inbox Details - Team Assignee"."inbox_name" = 'VIP Support Inbox'    )       OR (      "Inbox Details - Team Assignee"."inbox_name" = 'Support'    )    OR (      "Inbox Details - Team Assignee"."inbox_name" = 'VIP Escalation Inbox'    )    OR (      "Inbox Details - Team Assignee"."inbox_name" = 'Escalation I

351
Shaq Payne
Intercom Team
P
paulmwatsonNew Participant
asked in API & Webhooks
API Returns Cannot submit an array as a custom attribute value

Hello, We created a custom attribute with the list type called `Channel Networks`. When we try to update it via the API we get back the following error:```{  type: 'error.list',  request_id: 'REDACTED',  errors: [    {      code: 'nested_custom_attributes',      message: 'Cannot submit an array as a custom attribute value'    }  ]}```Other custom attributes work fine, just list/array type ones fail.```const respIntercom = await fetch(`https://api.intercom.io/contacts/${contact_id}`,{method: 'PUT',headers: {'Content-Type': 'application/json','Intercom-Version': '2.12',Authorization: `Bearer ${process.env.INTERCOM_ACCESS_TOKEN}`},body: JSON.stringify({"name": userData.user.name + " TEST","phone": userData.user.phone,"last_seen_at": userData.user.last_online,"signed_up_at": userData.user.created_at,"custom_attributes": {"ACME": userData.user.acme,"Channel Networks": ["Channel 1", "Channel 2"],}})});```

261
Jacques Reynolds
Intercom Team
J
Jay GNew Participant
asked in API & Webhooks
Is there any way to create a callback request through the API?

Hi,I wanted to know if there is any possible way to trigger a callback request through setting a conversation attribute ‘last_inbound_call_estate’ to ‘Awaiting callback’. As all I can seem to find is that this data attribute is only accessible through the phone workflow and can only be added and modify by Fin though the workflow.It would be nice if there was an option to set the ‘last_inbound_call_estate’ to ‘Awaiting callback’ for any conversation so the active team members would automatically get the call in their inbox, just like when they request a callback through the phone workflow, but without them having to actively call… Wether it is though API or through a messenger workflow it would be nice to integrate.

241
Jacques Reynolds
Intercom Team
V
Victor AndréeNew Participant
asked in API & Webhooks
Update custom object references through REST API v2.13

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

513
V
B
Bounce EngineeringNew Participant
asked in API & Webhooks
Semicolon/side panel showing up after the "Need help?" badge

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!  

673
mateusz.leszkiewicz
Intercom Team
A
Aaron ByromNew Participant
asked in API & Webhooks
Image upload with Rest API

Hey there, I’m finding it difficult to understand the rest API docs around file uploads. I would love to have a user fill out a form, and attach an image, and this would be submitted by the API to create a ticket. I see that the “File” type is supported in the tickets, however I’m finding difficulty in figuring out what Intercom wants as a file.  Is there any more documentation that you could point me towards? Or could you provide a quick example of what an image upload would look like with the API?  Thanks, Aaron. 

11208
E
E
Eduardo LNew Participant
asked in API & Webhooks
"WhatsApp Number" attribute

I'm creating a user in the api and filling in the phone field. I Want fill a field "WhatsApp Number" How I do that?  there is nothing in the documentation

4516
O
L
lifanActive User
asked in API & Webhooks
Search ticket with ticket_id in the rest API

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.

523
L
P
PodporaNew Participant
asked in API & Webhooks
Discrepancy in Pagination Format for /companies/list Endpoint

Hi, I am currently using the OpenAPI specification provided in your YAML file to generate an API client for the /companies/list endpoint. According to the YAML, pagination is implemented via a "pages" object, which includes a "next" property defined as a starting_after_paging object. This object is expected to contain properties like per_page and starting_after.However, the actual API response returns the "next" property as a plain URL string, for example:"pages": { "type": "pages", "next": "https://api.intercom.io/companies/list?page=2&per_page=1&order=desc", "page": 1, "per_page": 1, "total_pages": 223},"total_count": 223I have verified that this behavior is consistent even when using the API testing tool provided at https://developers.intercom.com/docs/references/rest-api/api.intercom.io/companies/listallcompaniesCould you please clarify whether this is a known issue or an intentional change in the API implementation that has not yet been reflected in the YAML documenta

471
Paul Byrne
Intercom Team
R
Rasmus Wedel-Heinen AndersenNew Participant
asked in API & Webhooks
Fowarding Files via API

Hey!We are creating tickets for some chats and sending the ticket attributes to an external tool using POST API requests. I’m able to forward all attributes except for any files added to the ticket, as the file attribute isn’t saved like the others.Is there a way to include links to the files in my API call through the Action Builder? I see that the files are stored like this, so I would just need a way to include this in the call. https://downloads.intercomcdn.com/i/o/qwum5ehb/1430332547/0a18547e88a0534a2b11dc66de1c/About+-+Wolt+%28Germany%29.pdf?expires=1742396400&signature=71937dcca587c48f45395961771de4a294247409d94427ef8a309fcc0f603793&req=dSQkFsp9n4RbXvMU3HP0gCfl8Ixw9B04fnL9Av84zX8P2bzVoXE%3D%0A

292
R
M
Mitch EvansNew Participant
asked in API & Webhooks
Optional/nullable params in Custom Action

Hello, I have a custom action that is supposed to send a request to my server along with multiple url params attached.The problem is however, not ALL of the params are sent for every request. Yet, since they are declared in the Request section of Custom Actions the call fails presumably because not every param has a value. The questions are, 1.) are we able to set these params to be “optional” and I’m just missing the option? 2.) Why can’t Intercom just recognize that this param is empty, and input a null, or avoid the param all together and leave validation up to the server receiving side? AKA, my server.I just feel like this product is feature limited to the point its useless, at least for my use case. And yes, I have tried for hours to Google, watch Youtube videos, browse articles (even found this one), reach out to support (no response), and just plain ol’ trying things on my own before coming here. So don’t give me the ol’ “Search Google” non-sense. PRODUCTIVE AND SUPPORTIVE ANSWE

3779
E
N
nikospNew Participant
asked in API & Webhooks
CSP require-trusted-types-for 'script' header issue

Hi team,We're implementing the require-trusted-types-for 'script'; header in our app and have set up a default Trusted Types policy. However, the Intercom widget script fails on the following line:e.documentElement.innerHTML = t,withUncaught TypeError: Failed to set the 'innerHTML' property on 'Element': This document requires 'TrustedHTML' assignment. Has anyone encountered this issue before? Any suggestions on how to work around it while keeping Trusted Types enforcement?Thanks! 

323
Nathan Sudds
Top Expert ✨
D
DriboNew Participant
asked in API & Webhooks
[Feature Request] Send whatsapp templates via REST API

Hi guys,As far as I know, currently there is no option for sending Whatsapp templates via REST API (correct me if I’m wrong). Whatsapp don’t allow sending messages via their API directly if the number is already connected to your system. That leave us without options in order to have only 1 single point of contact number for receiving user’s questions and being able to automate templates for our users. Other competitors (like Messagebird) already allow to send whatsapp templates via their API.So the question is, is there any plan to allow this in your API? Is there any ETA? This feature is quite important and if there is no plan to implement it would make customers contemplate switching providers. Thanks in advance.

492
D
M
Matheus SimonaciNew Participant
asked in API & Webhooks
Issue with searching tickets containing spaces in Intercom API

I'm experiencing an issue when using the Intercom API to search for tickets. When I try to search for a title that contains spaces, the API does not return the expected results. For example: The query below returns the ticket correctly: { "query": { "field": "title", "operator": "~", "value": "Atraso" } } However, when I add a space after "Atraso", no results are returned: { "query": { "field": "title", "operator": "~", "value": "Atraso " } } I have already tried the following approaches without success: Using regular expressions with \b Encoding the space as %20 Using the exact match operator "=" Expected result :[ { "type": "ticket.list", "pages": { "type": "pages", "page": 1, "per_page": 20, "total_pages": 1 }, "total_count": 1, "tickets": [ { "type": "ticket", "id": "9", "ticket_id": "3", "ticket_attributes": { "_default_title_": "Atraso na criação de atividades no Pipedrive", "_default_description_": "Solicitação de análise urgente de atraso na criação de atividades no Pipedr

181
Jacques Reynolds
Intercom Team
N
Nawfal MellahNew Participant
asked in API & Webhooks
401 error "token_not_found" but the access token is provided

Hello,I am using Intercom API in a GCP cloud run to do several things, especially updating a user.Sometimes it works, but sometimes I get an 401 error: “token_not_found”, and I checked multiple times with logs: I am always sending the access token and it’s the right one. “intercom_user_id” is also the right one.I also checked multiple times my server and logic, and there’s no error.Here are some request ids where this error happened: 0003sad4ua316ingi1l0, 000an1qat9nc63bsg160, 0021017ivsn8tt93ipd0.Here is the call in python:url = f"https://api.intercom.io/contacts/{intercom_user_id}"headers = { "Authorization": f"Bearer {settings.INTERCOM_ACCESS_TOKEN}", "Intercom-Version": "2.12", "Content-Type": "application/json",}update_dict = intercom_profile.model_dump()try: response = await httpx_client.put(url=url, headers=headers, json=update_dict) if response.status_code != 200: log.info(response.json()) log.info(f"INTERCOM_ACCESS_TOKEN: {settings.INTERCOM_A

341
mateusz.leszkiewicz
Intercom Team
T
Tanay SNew Participant
posted in API & Webhooks
How can I fetch date from my workspace and save it to another platform?

I am doing research on fetching data from my intercom account and save to another platform. In the way i just wanted to know if i can fetch anyone's app created app credentails i.e client_id,client_secret using account username and password. I have also gone through the api doc provided by Intercom but didn't found anything relevant to this.  So anyone can tell me whether it is possible in Intercom or not?

403
E
Ask a question
Terms & ConditionsCookie settings