Identity Verification ensures 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 to each User request, alongside their 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, the Intercom Messenger will not load or accept requests for a logged-in User without a valid user_hash. The user_hash is calculated using a secret key. 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.
How does Identity Verification affect my Leads and Users?
We make a clear distinction between:
Visitors - unknown customers to your site who aren’t logged in and don’t have a conversation history with you,
Leads - customers who start a conversation with you or reply to a message, and
Users - customers who sign up to your product and log into an existing account.
With Identity Verification enabled and correctly set up, your Users and Leads will experience the Messenger as normal. There is no extra action required from them to authenticate themselves. Your logged-in Users will greatly benefit from this added layer of security.
What if I don’t have any logged-in Users?
If you are using the Intercom Messenger just to talk to Leads on your site or unidentified mobile users in your app, you should still enable Identity Verification. While you cannot send user_hashes as you would for logged-in Users, simply toggling the Identity Verification feature on will protect you from User impersonation and associated confidentiality risks.
How do I set it up?
Enforce identity on web
Step 1:
Follow the instructions on the Identity Verification page in your settings. There are a number of options depending on how you've installed Intercom. You can see more examples of generating the user_hash in different programming languages and libraries here.
Step 2:
Once you’ve set up Identity Verification in your code and started sending user_hashes for each user, 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.
Enforce identity on your mobile app
Step 1:
First, select "Enforce identity on iOS" or "Enforce identity on Android" under Security in the left-hand Settings menu.
Step 2:
Retrieve the Identity Verification secret and store it in a secure place on your server.
Important: You should not store the secret in your mobile app; your server should only send the user_hash to your mobile app.
Step 3:
Then, follow our mobile SDK guides for the platform you’re using:
Note: Enabling Identity Verification will stop old versions of your app communicating with Intercom if they don’t send a valid user_hash.
Step 4:
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.
How can I verify that Identity Verification is working?
Once you have set up Identity Verification, we recommend verifying that it’s working properly. In your Security settings you can see whether Intercom has received valid user_hashes for your Users under “Active integrations with logged-in users”:
Can I turn off Identity Verification?
You can turn Identity Verification on or off at any time by navigating to Settings > Security > Enforce identity on web. This can be useful while you’re developing.
Important: 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.
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. Find instructions on how to open your browser console here.
Some other things to check:
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.