Skip to main content
Set up Identity Verification for web and mobile

Enhance your security and prevent impersonation by setting up Identity Verification.

Penny-Merelle avatar
Written by Penny-Merelle
Updated over a week ago

Setting up Identity Verification will require technical changes to your Intercom Messenger installation and requires access to server side code most of the time.


Set up Identity Verification on web

Select your installation method

First go to Settings > Channels > Messenger > Install and open Secure the Messenger with Identity Verification.

Then choose how you installed your Messenger (with an NPM package or with an integration).

If you’ve installed Intercom with WordPress or Shopify, you can go ahead and enforce Identity Verification with no configuration needed (only available for US hosted workspaces).

Generate an HMAC code on your server

For Code snippet installations, you'll need to generate an HMAC on your server for each logged-in user and send it to Intercom.

First, choose how you want to uniquely identify your users via User ID or Email.

Note:

  • If you choose to send both to Intercom, the User ID will take preference.

  • Keep your secret key safe! Never commit it directly to your repository, client-side code, or anywhere a third party can find it.

Then choose the server-side language or framework you're using to get your code to generate an HMAC for your app.

Update your site to send the HMAC

Everywhere you load user data and have a window.intercomSettings code snippet, add a new attribute called user_hash and assign the HMAC code to it.

We offer an updated code snippet which includes HMAC value as a parameter sent to the Intercom Messenger. Simply click Copy code to use it.

Check the installation

Once you’ve set up Identity Verification and started sending user_hashes for each user, check the installation is working as expected.

Click on Check installation. This button will display a table of the domains where the Messenger has been found, as well as their Identity Verification status. A green tick indicates success, and a warning triangle indicates that the Messenger was not found with the correct Identity Verification settings.

Ensure that you have dealt with all errors on all the domains in the list. These are all the domains from which we have received a ping.

You can also use our hash checker to verify that the user hash values you're sending over to Intercom are correct, ensuring that Identity Verification will work correctly. Here, you can verify what the expected user hash is based on user_id or email (if you're not using user_id's).

All of your ping requests must include user_hash for you to enforce Identity Verification on web.

Enforce Identity Verification for Messenger

If you’ve correctly modified your Messenger code and see no errors, you can now enforce Identity Verification by toggling on the option "Enforce Identity Verification for messenger" and clicking Enforce. This may take 5-10 seconds to activate.

Once enforced, any requests without user hashes will be rejected, preventing impersonation of your users via the Messenger.


Set up Identity Verification on your mobile app

Similarly to the Web installation, you'll find the toggle for iOS, Android & React Native under Install for mobile:

Then retrieve the Identity Verification secret key and store it in a secure place on your server.

You should not store the secret key in your mobile app; your server should only send the user_hash to your mobile app.

Now follow our mobile SDK guides for the platform you’re using:

Once you have tested that your Messenger is working as expected in your app, turn off Identity Verification and publish the new Identity Verification-enabled version on the App Store. When you reach a high level of adoption, toggle Identity Verification on, which will then start enforcing it for all versions of your app.

Enabling Identity Verification will stop old versions of your app communicating with Intercom if they don’t send a valid user_hash.


How to turn off Identity Verification

You can turn Identity Verification off at any time by navigating to Settings > Channels > Messenger > Install and scrolling down to the final step of Secure the messenger with Identity Verification on your chosen platform setup to toggle off "Enforce Identity Verification for messenger". This can be useful while you’re developing.

Your app will be unprotected while Identity Verification is turned off. This means one User of your app could attempt to impersonate another, and see their conversations or modify their data in Intercom.


How to rotate your Identity Verification secret

We can rotate your identity verification secrets for you from our end, this cannot be done from your own workspace. To perform this rotation we will need you to contact us directly and to do the following:

  1. Have you disable identity verification from within Intercom (individually for web, iOS or Android)

  2. We will then rotate the specific secret

  3. You will refresh the page to view the new secret

  4. You then will implement the new secret into your code to generate the proper user_hashes

  5. Lastly, you'll enable identity verification again

There will be no downtime, however, during the completion of steps 2-5 your users will be able to use the Messenger without identity verification enabled.

Find out more about Identity Verification or try our troubleshooting tips if you're experiencing issues with setup.


💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts


Did this answer your question?