Enable identity verification for web and mobile

Identity verification helps ensure conversations between you and your users are kept private, and that one person can't impersonate another. We strongly encourage all Intercom customers to set up and enable identity verification.

How does identity verification work?

Identity verification for web requires you to add an encrypted user_hash (HMAC) (that you generate on your server using SHA256) to your installation snippet alongside your user’s email or user_id.

With identity verification for mobile, your app’s server will return the user_hash to your Android or iOS app where you’ll use it to register your users.

While identity verification is enabled, Intercom won’t accept requests for a logged-in user without a valid user_hash. The user_hash is calculated using a secret key, which you should never share. Without this secret key, no third party can send Intercom a valid user_hash for one of your users, so they can’t impersonate your users

Important: It's not possible to set up identity verification for anyone who you don’t have a user ID or email address for, like new unidentified leads for example.

Do I need identity verification?

To better protect your users’ data and conversations, we strongly recommend you enable identity verification. If you only chat to visitors, identity verification is not essential. However, we still encourage you to enable it in the Intercom for web settings. This will help prevent third parties from performing malicious actions.

How does identity verification affect my visitors and users?

With identity verification enabled and correctly set up, your users, leads and visitors will experience the Messenger as normal. There is no extra action required from them to authenticate themselves. However, your logged-in users will greatly benefit from this added layer of security.

How do I set it up?

For web:

Once you’ve set up identity verification in your code, you can check the installation and enforce it in your Intercom settings.

Note: If you’ve installed Intercom with the WordPress app, you can enable identity verification in your settings with no configuration needed. You can see more examples of generating the HMAC user_hash in different programming languages and libraries here.

For your mobile app

First, (select ‘iOS’ or ‘Android’ under 'Identity Verification' in the left-hand menu. Then, retrieve the identity verification secret and store it in a secure place on your server:

Note: Enabling identity verification will stop old versions of your app communicating with Intercom if they don’t send a valid user_hash.

We recommend that you complete setting up identity verification and test that everything is working. Then, turn off identity verification and publish the new identity verification enabled version on the App Store. Once you reach a high level of adoption you should toggle identity verification on which will then start enforcing it for all versions of your app.

Can I turn off identity verification?

You can turn identity verification on or off at any time in your settings. This can be useful while you’re developing. However, your app will be unprotected while it’s off. This means one user of your app could attempt to impersonate another, and see their conversations or modify their data in Intercom.

Troubleshooting common issues

If you’re having trouble setting up identity verification or just want to confirm that it’s working, visit any page in your web app with the Intercom Messenger installed and check if it loads.

If it doesn’t load, then take a look at your browser console and you should see an error explaining the specific issue. For instructions on how to open your browser console, click here.

Some possible causes might include:

Are you sending a user_id or email address along with the user_hash? If you just send the user_hash the identity verification check will fail.

Are you generating the hash with the correct data? If you’re sending both user_id and email, your user_hash must be generated with the user_id. If you’re sending just a user_id, your user_hash must be generated with that user_id. If you’re sending just the email address, your user_hash must be generated with that email address.

Are you using the correct identity verification secret? Web, iOS and Android all have unique secrets and you must use the one provided in your Intercom settings. Making up your own won't work.

Have you enabled (and configured) identity verification in the correct environment? Your [TEST] workspace and production workspace must be configured separately as each has its own set of unique identity verification secrets.

Is this the latest version of your code? If this is an older version of your app, or your JavaScript code is cached you might not be sending a user_hash with your user data in which case the messenger won’t load.

If you’re still having trouble with identity verification, reach out to our support team through the messenger and we’ll be happy to take a look!