Learn how to integrate Fin Messenger with Zendesk, customize the workflow, and control how conversations are handed off to your teammates.
Integrate the Fin Messenger with Zendesk
Choose how Fin should hand off to Zendesk
Go to Deploy > Fin Messenger and choose what should happen when Fin can't answer a customer:
Hand-off to Zendesk agent: Creates a live messaging conversation in Zendesk.
Create Zendesk ticket: Ends the session in Fin and creates a Zendesk ticket with a transcript.
Determined by situation: e.g., live chat during office hours, ticket after hours.
Your selected handoff method determines which Zendesk APIs you must connect.
Capability | Requires Zendesk API (OAuth) | Requires Sunshine Conversations API |
Create Zendesk ticket | Yes ✅ | No ❌ |
Hand-off to Zendesk agent | Yes ✅ | Yes ✅ |
Determined by situation | Yes ✅ | Yes ✅ |
Connect to Zendesk using OAuth
OAuth is the primary method for connecting Fin with Zendesk. OAuth removes the need to manually manage API tokens and ensures continued compatibility with Zendesk changes.
Go to Deploy > Fin Messenger.
Under Zendesk API, select Connect.
Sign into Zendesk using OAuth and approve access.
Return to Fin to confirm the connection shows as Connected.
Note: Zendesk is deprecating API-token authentication. All new customers must connect Fin to Zendesk using OAuth.
New non-contracted customers: OAuth is required.
New contracted customers: OAuth is required once enabled on the workspace.
Existing customers: API-token connections continue working, but if disconnected, reconnection must use OAuth. A persistent banner will appear until OAuth is enabled.
Connect to the Zendesk Sunshine API
If your workflow includes Hand-off to Zendesk agent, you must also connect the Sunshine API. Sunshine API credentials remain key-based; OAuth does not replace them.
Provide the following details from Zendesk Admin Center > Apps & Integrations > Conversations API:
App ID
Key ID
Secret Key
Once you have copied over all of the above, select Connect.
Note: The Zendesk Conversations API has been deprecated in favor of their Sunshine API. You will need to have a Sunshine license in order connect the conversations API.
If you do not see the option for "Conversations API" in your Zendesk admin settings under Apps and integrations > APIs > Conversations API, then you likely do not have a Sunshine license and will need to reach out to Zendesk support to obtain one.
How the Zendesk Sunshine API works
The Sunshine API keeps your Fin and Zendesk conversations synchronized in real time. Fin sends and receives API calls:
On every inbound customer message
On every Fin response
When conversations are assigned, escalated, or closed
If a customer starts in Fin Messenger, Fin creates or finds the corresponding Sunshine user.
If a conversation starts in Zendesk Messenger, Fin maps messages back into the Fin workspace.
Enable multiple conversations in Zendesk
If using Hand-off to Zendesk agent or Determined by situation, Zendesk requires Multiple conversations to be enabled.
Click Manage in Zendesk when prompted in Fin.
Enable Multiple Conversations in the Zendesk Messaging settings.
Return to Fin and click Refresh.
Build your workflow
Configure greeting and hand-off workflow
From the integration screen, click Manage workflow. A template is provided, but you can fully customize:
When Fin should answer
How Fin greets customers
What happens on escalation
What data to collect before hand-off
At the end of any unresolved path, Fin unassigns itself and applies the routed-to-the-team tag.
Click the Let Fin handle step in your workflow to customize the following:
Set expectation for human support - Show teammates presence in a messenger conversation. Disable this if your team all work in another tool or no one is monitoring the inbox.
Follow up with inactive customers - Decide what happens if the customer doesn’t respond after Fin answers.
Ask for more information before handover - Collect more information when a customer asks to speak to the team. When collecting more information Fin may provide an additional answer—increasing the likelihood of a resolution.
Create Zendesk ticket on resolution - Fin can create a Zendesk ticket for every conversation it resolves, helping your team track customer questions and issues. For each conversation resolved, Fin will add a transcript of the conversation and attributes to a closed ticket in Zendesk when this setting is enabled.
Ask for conversation rating (CSAT) - Choose to send a CSAT survey after customers interact with Fin.
Auto-close abandoned Fin conversations - Decide how long Fin should wait before a customer is considered inactive, when to close inactive conversations, and customize what Fin says when closing the conversation.
Configuring auto-close settings
Fin allows you to customize auto-close behavior through specific actions within your workflow. The relevant settings are located in the Let Fin Answer step. Follow these steps to manage and customize auto-close configurations:
Within the Let Fin handle step, find the section labeled Auto-close abandoned Fin conversations.
Use this section to define the specific conditions under which a conversation is considered abandoned. Specify the delay time before the conversation is automatically closed.
To configure the timing for inactivity-based closures, adjust the Close-on-inactivity timing settings under the same Let Fin handle section. These settings allow you to manage how long Fin will wait before closing a conversation when no customer activity is detected.
Extending the auto-close timeframe can help reduce the number of assumed resolutions. For instance, increasing the delay time from the default (e.g., 8 hours) to 24 or 48 hours gives customers more opportunity to respond before conversations are closed.
Tips:
Set realistic time delays: A delay that is either too short or too long may result in poor customer experience. Aim to balance responsiveness with giving customers adequate time to reply.
Define conditions clearly: Ensure that the criteria for abandonment and inactivity are well-defined and suited to your support use case.
Test the settings: Run tests to confirm that the chosen settings align well with your workflow requirements and customer needs.
You can tailor the experience further in the workflow builder 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:
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. | 
|
Customise Zendesk ticket subjects using attributes
If your hand-off creates a Zendesk ticket, you can click on the Create Zendesk ticket action to customize the ticket subject using attributes in your Fin workspace.
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).
Assign tickets to specific Zendesk organizations
If your Zendesk workspace uses organizations and a user belongs to more than one, you can control which organization a ticket is assigned to via the JWT token.
To do this:
Create or use an existing organization in Zendesk with an external id, this can be created through the Zendesk API here.
Include a
companyfield in the JWT with two attributes:{
"id": "457", // This should match the external ID of the Zendesk organization.
"name": "Examply Org"
}Set up a Fin Messenger workflow with the Create Zendesk ticket hand-off.
Any tickets created from the Fin Messenger will be automatically assigned to the organization defined by the
external_idin the JWT (as long as that user is within the organization). Note: This is only available in Fin Messenger on channels that support JWTs (email is not supported).
Tip: You can create and manage multiple Fin workflows directly within your Fin workspace. This enables you to tailor customer experiences for different messaging scenarios and to set up separate “test” workflows that are only triggered for your team.
Install the Fin Messenger
To install the Fin Messenger, go to Deploy > Fin Messenger > Install. You will need to install the messenger for either your website or web app, or for your mobile app.
Install for web
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 Fin 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 Fin Messenger with JWTs
If you have the Fin Messenger installed on your site for logged in users, it's essential to secure it and prevent bad actors from impersonating your users or sending unauthorized data.
JSON web tokens (JWTs) prevent third parties from impersonating your logged-in users and seeing their conversations. We strongly recommend that all Fin customers enforce JWT authentication.
With JWT authentication enabled, Fin automatically synchronizes user and organization fields from Zendesk to your Fin workspace each time the Fin Messenger is launched or a new message is received via the Zendesk Messenger. This seamless data transfer allows for more dynamic and personalized customer interactions within your workflows.
Avoid over-reliance on URL-based segmentation: Do not use URLs alone to distinguish between logged-in and logged-out users. URLs can be bookmarked or accessed by unauthorized users, making it insecure. Combine URL-based segmentation with JWT for robust authentication.
Install for 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 Fin into your mobile apps and some code snippets to help with the installation.
Initialize Fin within your codebase
The next step is to initialize Fin within your mobile app’s codebase. You can also manage your API keys during this step.
The code snippet options for iOS | The code snippet options for Android | The choices for React Native |
|
|
|
Follow the instructions
Next, follow the platform-specific instructions to integrate Fin Messenger into your mobile app.
When setting up Fin Messenger for iOS
In Zendesk, navigate to Admin Center > Apps and Integrations > Conversations API.
Click Create API Key, name your key, and click Save.
Copy the generated key — it will appear in your Conversations API list.
In your Fin workspace, go to Deploy > Fin Messenger > Install > iOS, and paste the key into your initialization code.
Important:
Store your App ID, Key ID, and Secret Key securely — they won’t be shown again.
You can store up to 10 keys total.
You’ll need a Zendesk Suite Professional plan or higher.
Check installation
Click Check installation at the end of the setup to verify success.
You’ll see a confirmation if Fin Messenger has been detected, or an error message if something went wrong.
Secure the Fin Messenger with JWTs
If you have the Fin Messenger installed on your site for logged in users, it's essential to secure it and prevent bad actors from impersonating your users or sending unauthorized data.
JSON web tokens (JWTs) prevent third parties from impersonating your logged-in users and seeing their conversations. We strongly recommend that all Fin customers enforce JWT authentication.
With JWT authentication enabled, Fin automatically synchronizes user and organization fields from Zendesk to your Fin workspace each time the Fin Messenger is launched or a new message is received via the Zendesk Messenger. This seamless data transfer allows for more dynamic and personalized customer interactions within your workflows.
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:
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 Fin 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 Fin's use of WKWebView. There is a bug in Xcode 14 that triggers these warnings, and it is not an issue that Fin can fix.
They are just warnings and Fin 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.
Test Fin in the Fin 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.
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 Fin 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 Fin 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 Fin Messenger aligns with the external_id in Zendesk.
Go live with Fin for Fin Messenger
Now you’re ready to set Fin live for your customers. Go to Deploy > Fin 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 Fin-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. This behavior ensures that the conversation's status appropriately reflects the customer's needs, enabling smoother transitions to the team and reducing potential for unresolved tickets.
When the agent replies, it'll show up in the Fin 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.
Note: You can't use the Fin Messenger for both Fin and Proactive Support messages (such as outbound chats, posts, product tours, email, etc.)
Learn how to set up Fin for Zendesk tickets.