How it works

For a complete overview of how Fin for Intercom Messenger works, check out this walkthrough: Fin in the Intercom Messenger: How does it work?

Get started

To setup the Intercom messenger with your Zendesk account, go to:

Deploy > Intercom Messenger.

1. Integrate the Intercom Messenger with Zendesk

Configure how you'd like to hand-off

You will first need to decide how Fin will hand off to a human teammate when it is unable to answer.

Hand-off to Zendesk agent – A live chat will be created in Zendesk for a team member to continue the conversation.
Create Zendesk ticket – The user's session ends, and a Zendesk ticket is created with a summary of the conversation and collected data.
Determined by situation – The hand-off method changes based on the scenario, such as live chat during working hours or ticket creation after hours.

The method of connecting to Zendesk depends on the handover step that you choose:

	Zendesk API	Zendesk Conversations API
Create Zendesk ticket	✅	❌
Hand-off to Zendesk agent	✅	✅
Determined by situation	✅	✅

Connect to the Zendesk API

To connect to the Zendesk API, select Connect under the Zendesk API.

You'll need the following from your Zendesk account:

Your Zendesk subdomain - You can get this from the address bar when in the home screen of your Zendesk account.
Your Zendesk email - The email you use to login to your Zendesk account.
Your API token - You can get this in the Admin center of your Zendesk account, under Apps and integrations > APIs, and selecting Add API token.

Connect to the Zendesk conversations API

To connect to the Zendesk conversations API, select Connect under Zendesk conversations API.

You will be prompted to add the following:

App ID
Key ID
Secret Key

All of these can be found in the admin center of your Zendesk account under Apps and integrations > APIs > Conversations API. Once you have copied over all of the above, select Connect to Zendesk conversations API.

Enable multiple conversations in Zendesk

If you have selected Create Zendesk ticket as your hand-off, then you can continue to build your workflow.
If you have chosen Hand-off to Zendesk agent or Determined by situation, then you will need to enable multiple conversations in Zendesk.

When you connect to the Zendesk Conversations API, Fin automatically detects wether you have this setting switched on in Zendesk. If you do not have it switched on, simply click "Manage in Zendesk" and it will bring you directly to messaging settings in your Zendesk account where you can enable it.

Once you have hit save on the multi-conversation option in your Zendesk account, return to your Intercom setup and hit refresh to see this reflected in your setup.

2. Build your workflow

Configure greeting and hand-off workflow

Once you've configured the Zendesk integration step with your Intercom account, you will need to configure the way Fin greets and responds to customers or hands off when it's unable to help, by selecting Manage workflow. There will be a pre-built template here, but you can customize it to your liking.

Here, you can define when Fin should respond, and what should happen if the conversation is escalated to a team. At the end of all paths (except when Fin resolves the query), Fin will un-assign itself and apply the “routed-to-the-team” tag.

You can tailor the experience further by:

Creating different branches based on your conditions.
Choosing when Fin answers.
Having Fin send a message.
Providing reply buttons.
Collecting data.
Collecting the customer reply.
Adding internal notes.
Adding an AI generated summary of the conversation.
Auto-classifying ticket attributes based on what the customer said.

Note:

You must be in Edit mode to be able to make changes to your workflow. Select Edit in the top right of the workflow editor screen.

In the final hand-off path of the workflow, you can choose how Fin hands over the conversation:

Create a Zendesk Ticket: Ends the users session in Intercom and creates a ticket with a conversation summary and collected data.
Hand-off to URL: Redirects the user to a new URL in the same tab.
Hand-off with JavaScript: Uses handoff_with_javascript to define actions in Intercom Messenger.
Hand-off to Zendesk Agent: Starts a live chat in Zendesk for a team member to continue the conversation.

If a hand-off option has already been selected you can remove this option by hovering over it, clicking the 3 dots that appear and selecting delete.

Once you’ve finished customizing the greeting and hand-off to your team, click Save, or Set live to enable this for your messenger (you can also come back to set this live at a later stage).

3. Install the Intercom Messenger

To install the Intercom messenger, go to Deploy > Intercom Messenger > Install. You will need to install the messenger for either your website or web app, or for your mobile app.

Install for web

Choose how you'd like to install the Messenger

Firstly you will need to choose how you would like to install the messenger. If you select Code snippet, React, Angular, Vue, Ember or Shopify as the installation method, you'll have the choice of installing Intercom for website visitors without logins.

The instruction for installing Code snippet, React, Angular, Vue, Ember or Shopify will update as you select each of the options. For the methods listed that allow the installation for both Users with logins and Visitors without, you will need to copy the code snippet for each installation method you wish to use.

For Users with logins, you will need to switch on the toggle Enable connection to messenger to continue to the installation code.

Follow the instructions given

Now follow the instructions given for the method you selected. For example, if you selected Shopify you'll see the steps required for this installation method.

If you selected the Code snippet, React, Angular, Vue, or Ember method, you'll be provided with an NPM package containing a code snippet to copy and paste into the codebase of your own app. This snippet is pre-populated with your unique workspace ID, so it's ready to go.

You can also find the package directly on the NPM site.

There are several other templates available such as including the code snippet in a Basic JavaScript or Single-page app, or you can also use the Rails gem to install the snippet.

Click Copy code and paste it before the </body> tag on every page you want the Messenger to appear on your app.

After adding the code, you can visit any page where you have installed the messenger and it should appear in the bottom right hand corner or you can use the Check installation option in the install process.

Secure the web messenger with Identity Verification

To secure your messenger and prevent anyone from impersonating your logged-in users or seeing their conversations, you will need to choose how you installed your Messenger (with an NPM package or with an integration).

If you’ve installed Intercom with Shopify, you can go ahead and enforce Identity Verification using the Enforce Identity Verification for messenger toggle, with no configuration needed.

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. Then choose the server-side language or framework you're using to get your code to generate an HMAC for your app.

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.

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.

Important:

If you have attributes that are synced from Zendesk to your Fin workspace, it is not possible to update these attributes using the messenger code snippet. You will need to add these attributes in the Zendesk integration settings in your Fin workspace.

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 the 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.

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.

Once you’ve correctly modified your Messenger code and see no errors, you can enforce Identity Verification by toggling on the option Enforce Identity Verification for messenger. This can take up to 10 seconds to activate.

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

For a more details on Identity Verification, check out our complete guide to Setting up Identity Verification for web and mobile.

Install for mobile

Choose your installation platform

Firstly you'll need to choose your installation platform of choice; iOS, Android or React Native. All chosen platforms have steps specific to that platform and you'll be provided with options for how to install Intercom into your mobile apps and some code snippets to help with the installation.

Initialize Inercom within your codebase

The next step will be to Initialize Intercom within the codebase of your mobile app. You can also manage your API keys in this step.

The code snippet options for iOS	The code snippet options for Android	The choices for React Native
Swift Swift UI ObjectiveC	Kotlin Java	iOS Android

Follow the instructions

You will then need to follow the platform specific instructions to integrate the Intercom messenger in your mobile app.

The Check installation button at the end offers a success notification if the Messenger has been successfully found for your chosen installation, or it indicates whether something has gone wrong.

Securing the mobile messenger with Identity Verification

To secure the Messenger with Identity Verification on mobile, you will first need to choose the installation platform; iOS, Android or React Native.

If you choose React Native, then similar to the installation step, you will be asked to choose which platform you wish to install the React Native SDK with (iOS or Android).

Code snippets and instructions are provided on how to generate a HMAC code (Hash-based Message Authentication Code) within your backend codebase and provide it to the Intercom Messenger. This HMAC code is used by Intercom to verify the authenticity of user interactions in the Messenger.

An additional code snippet is provided so you can include the HMAC when initializing Intercom within your mobile app.

For React Native, we provide an example code snippet for how you can use the HMAC code to initialize Intercom with identity verification.

The final step in the identity verification process is to enforce identity verification. Once this is done all requests from the Messenger which do not include the valid HMAC code will be rejected.

Optional: Set up push notifications

Within this step you will again have the option of the installation platform; iOS or Android. You can configure push notifications from this section, but it will not guide you through the process. Instead our developer docs should be used for push notification setup:

iOS Instructions

Android Instructions

React native is not offered as an option for mobile push notifications.

This optional step is marked as complete when push notifications have been detected as set up for either an iOS or an Android app.

Important: Xcode 14 is now required to build Intercom iOS SDK v13.0.0+

In Xcode 14, there are several warnings logged to the console when the SDK is installed. The warnings stem from Intercom's use of WKWebView. There is a bug in Xcode 14 that triggers these warnings, and it is not an issue that Intercom can fix.

They are just warnings and Intercom continues to function as normal when they are present.

Here are the warning messages:

WKWebView Error - View Article and you see this in the console: Error acquiring assertion: <Error Domain=RBSServiceErrorDomain Code=1 "target is not running or doesn't have entitlement com.apple.runningboard.assertions.webkit" UserInfo={NSLocalizedFailureReason=target is not running or doesn't have entitlement com.apple.runningboard.assertions.webkit}>
This method should not be called on the main thread as it may lead to UI unresponsiveness.
[Sandbox] Could not enable Mach bootstrap, errno = 22.

4. Test Fin in the Intercom Messenger

Ensure Fin is ready

First you'll be asked to ensure you've given Fin sufficient training.

This is important before starting live testing.

We recommend reading our complete guide on all of the ways you can train Fin so its able to answer your customers questions as accurately as possible.

Training Fin

Live Test

Once you've checked that Fin is sufficiently trained and customized the messenger to match your company branding, you can run a live test.

This is the best way of seeing exactly how Fin in the Intercom Messenger will look and behave within the website or app that you've installed it, without any customers seeing it.

Enabling live testing activates Fin and turns on the messenger behind a test URL for the website where you've it.

Live testing mode is enabled

Launching the live test

Testing for mobile

For testing on mobile, you would need to install on your staging app first, so you can run any testing before setting it live.

Validate your setup in Zendesk

We recommend you test that the correct users are assigned as the ticket requester in Zendesk.

To confirm this:

Start a conversation in Intercom Messenger while ensuring that the correct user_id or email is being passed.
When Fin hands off the conversation, check the new ticket or live chat created in Zendesk.
Verify that the requester matches the expected user.
If the requester does not match, confirm that the user_id in Intercom Messenger aligns with the external_id in Zendesk.

5. Go Live with Fin for Intercom Messenger

Now you’re ready to set Fin live for your customers. Go to Deploy > Intercom Messenger > Go Live and select Go Live.

Customer experience

When a customer opens the Messenger they'll see a greeting from Fin (this can be customized).

After a customer sends a message, a ticket is created in Zendesk and the intercom-messenger tag will be applied. Using Zendesk Triggers you can decide when the ticket should be automatically assigned to Fin.

Conversations that get assigned to Fin will apply the fin-involved tag.

If Fin has relevant knowledge available to answer, Fin will respond and cite the sources it used, mark the ticket as solved, and apply the following tags:

fin-resolved: Fin has resolved the ticket (either soft or hard resolution).
fin-soft-resolution: Fin has resolved the conversation, but the customer hasn't confirmed it.

If the question is ambiguous, Fin will ask clarifying questions and mark the ticket as pending and pass it to the team if the customer doesn't respond in 3 minutes.

If it doesn't have an answer, it'll hand the ticket off to your team by unassigning itself and marking the ticket as open.

The customer can ask follow-up questions and Fin will follow the same process.

If the customer says that it helped, the “fin-soft-resolution” tag will be removed and “fin-hard-resolution” applied.

If the customer asks to talk to the team, Fin will unassign itself from the ticket, remove the “fin-resolved” and “fin-soft/hard-resolution” tags and apply the “fin-routed-to-team” tag. Using this tag you can create additional Zendesk Triggers to route the ticket further.

When the agent replies, it'll show up in the Intercom Messenger. If the customer is offline and their email is known, an email notification will be sent allowing them to continue the conversation over email.