You can select which version of the API to apply to any given app. Visit your Developer Hub page to see a list of all your apps. From there, you can select which version of the API to apply to any particular app by:
- Selecting it via your
Developer Hubapp settings page, or
- Setting the version on each API call via an HTTP header
❗️ Always test new versions of the API
Some API versions may be breaking changes and require you to change your code if you are using that feature. We will highlight this when we provide information on the new version but you should always test new versions of the API to ensure they are fully compatible with your system
- Go to your Developer Hub and choose the relevant app.
- Then go to the
API Versionmenu, click on the
Change versionbox and select your new version. Once you have selected the appropriate version for your app all subsequent API requests will use this version.
Any conflicts between the topics available in the new version and the topics in the existing subscription will be displayed in a table below. Topics which are not available in the new version will have a status of 'Off'. These will need to be deleted before proceeding. If you wish to continue receiving webhooks for the topic, please check the webhook topics of the respective version.
- Identify the version you want to test (e.g. 1.x or 2.x). You can check the change log or look at the available versions in the app dropdown above to confirm the version number you want to use.
- Add an HTTP header of
Intercom-Versionto your API request.
- Using the
Access tokenfor your app make an API request with the header and the appropriate version.
httpstat https://firstname.lastname@example.org \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Accept: application/json' \ -H 'Intercom-Version: 1.1'
There are two options for testing new versions"
- Via the API
- Via a Private app
The best way to test new versions of the API is by setting the version in a HTTP header (see above). That way you can check what has changed and see whether it is compatible with your code, or whether you need to make a change before adopting the new version.
Alternatively, you can create a new private app on the target API version. Ensure you have selected the desired webhook topics, and provided a webhook url endpoint. Then you can use Intercom to test the new webhook topics and payloads. This will allow you to check see whether the version is compatible with your code, or whether you need to make changes before adopting the new version.
Yes, if you select a new version for your app and you discover an issue you can switch back to an older version.
You can start by setting the version via the HTTP header. This way you can ship code to production which changes the version and any new code needed at the same time. Once this is working in production you can change the version in your app and then remove the headers if you like.
For OAuth apps, this setting also dictates which version your clients use. All access tokens granted via OAuth (even those granted before the change) use the version that you have specified in your app settings and/or HTTP header.
Yes, but the header version in the API request will override the version selected in the app.
The change log is the best place to find information on the different versions and the changes they contain. We will highlight breaking changes in the change log clearly so you are aware of versions that may require you to make a change on your end.
Usually, but there may be security updates which necessitate mandatory changes. In these cases we will attempt to minimize any impact on older versions. For example, if we have to remove an attribute we will do that in the new version and may only change the value in older versions so as to minimize the impact until you upgrade to the newer version.