Zendesk Messaging

Overview

Zendesk Messaging Glass is Ada’s integration with the Zendesk Messaging asynchronous chat product. This integration enables Handoffs from your AI Agent to live agents in Zendesk, giving you access to Ada’s full feature set within your Zendesk environment.

What is asynchronous chat?

Asynchronous chat means that conversations between end users and your live support agents can extend indefinitely, until either the end user or agent ends the chat manually. It is not limited by automatic timeouts or disconnects, as is the case with session-based chat platforms like Zendesk Chat.

Requirements

Ada Glass for Zendesk Messaging requires that your Zendesk and Ada accounts have the following products enabled and configured:

• Zendesk
  • Sunshine Conversations
    • Channel: Web Messenger
  • Zendesk Agent Workspace
• Ada
  • Ada Glass for Zendesk Messaging
  • Sunshine Conversations channel integration

Capabilities & configuration

Zendesk Messaging Glass provides Handoff capabilities for asynchronous conversations between end users and live agents.

Key capabilities

• Asynchronous conversations: Conversations can extend indefinitely without automatic timeouts.
• Seamless transitions: End users and agents interact in the same chat window.
• Persistent history: Conversation history persists across sessions unless manually cleared.
• Department routing: Route Handoffs to specific Zendesk departments.
• Zendesk field mapping: Map Ada variables to Zendesk ticket fields.
• Automatic return: End users automatically return to your AI Agent when tickets are solved.

Quick start

Complete these steps to set up Zendesk Messaging Glass for Handoffs. See Implementation & usage for detailed instructions.

Implementation & usage

Configure Zendesk Messaging Glass and set up the Handoff block by completing the following steps.

Configure Zendesk Messaging Glass

Connect Ada to your Zendesk Messaging environment.

To connect your Zendesk account:

Follow the steps in Connect your Zendesk account to authorize your Zendesk subdomain.

To connect Sunshine Conversations:

If you have not already connected Sunshine Conversations, follow the steps in Sunshine Conversations setup to connect your app. This is required before configuring Zendesk Messaging Glass.

To configure the Zendesk Messaging integration:

1. On the Ada dashboard, go to Config > AI AGENT > Handoffs. Then, on the Integrations tab, beside Zendesk Messaging, click Configure.
2. Confirm that your Zendesk subdomain is pre-populated in the configuration modal. If it is not, select it from the drop-down.
3. Click Finish, then close the success dialog box.

Enable multi-conversation support

Enable multi-conversation support in your Zendesk messaging settings. This is required for Zendesk Messaging Handoffs, regardless of whether you also use Sunshine Conversations for social channels. Without it, end users cannot cleanly end conversations during a Handoff state and continue talking to the Zendesk ticket until it is closed.

To enable multi-conversation support:

1. In Zendesk Admin Center, in the sidebar, click Channels, then select Messaging and social > Messaging.
2. At the top of the page, click Manage settings.
3. Under Web Widget and Mobile SDKs, expand Multi-conversations.
4. Click Set up multi-conversations.
5. Click Turn on multi-conversations for your account, then select the channels where you want to offer it. This is required for the Ada web widget channel.
6. Click Save settings.

Create an end conversation trigger

Create a trigger in Zendesk to automatically end the agent conversation once the ticket status is set to solved. This trigger releases the end user from the Zendesk agent conversation and allows them to resume chatting with your AI Agent.

To create an end conversation trigger:

1. In the Zendesk Admin Center, go to Objects and rules > Business rules > Triggers, then click Create trigger.

2. On the Add new trigger page, add a trigger name, description, and category.

3. Under Meet ALL of the following conditions, click Add condition, then use the drop-down menus to set the condition to:

   • Category: Ticket > Status
   • Operator: Is
   • Value: Solved

4. Under Actions, click Add action, then use the drop-down menus to set the action to:

   • Category: Ticket > Status
   • Value: Closed

5. Click Create trigger.

With the trigger in place, end users are now automatically released back to your AI Agent when the agent selects Submit as Solved at the end of a live support conversation.

Set Ada as the default switchboard integration

For Zendesk Messaging Handoffs to work, your AI Agent must be set as the default for all channels in Zendesk. This makes it the default switchboard integration, so end users reach your AI Agent first. If it is not set as the default for all channels, incoming messages can bypass your AI Agent and go straight to Zendesk’s own AI agent.

To set your AI Agent as the default for all channels:

1. In Zendesk Admin Center, in the sidebar, click AI, then select AI agents > AI agents.
2. Under Other, in the Marketplace bots card, click Manage marketplace bots.
3. Locate the Ada Agent in the list.
4. Click the Options menu, then select Set AI agents as default for all channels.

To verify your AI Agent is set as the default for all channels:

On the Marketplace bots page, confirm the Default badge appears next to your AI Agent. If it does not, repeat the steps above. For more information, see Managing third-party bots in Admin Center in Zendesk’s documentation.

Authenticate end users

Use an Ada identity token unless your server already mints Zendesk JWTs. Both methods identify end users during a Handoff, so agents see the correct profile and ticket history. Identity tokens also keep Ada conversations available across devices.

Both methods need the Messaging SDK.

Use an Ada identity token

Request a fresh token for each exchange. Keep your Ada API key on your server.

To configure an identity token:

1. Create or look up the end user with an external_id through the End Users API. The Ada identity token has no effect on a Zendesk handoff without an external_id.
2. Request an identity token from your server through the Auth Tokens API, using the returned end_user_id. Include optional verified_email and name fields for verified email linking.
3. Pass the token to the SDK as identityToken.
4. When the end user signs out, call reset().

See the identity token setup guide for web and mobile code.

Use a Zendesk JWT

Use this supported alternative when your server mints Zendesk Messaging authentication JWTs.

To configure a Zendesk JWT:

1. In Zendesk Admin Center, create a signing key under Messaging authentication.
2. Share the key ID and secret with your Ada team. They add them to your Zendesk Messaging integration.
3. On your server, sign a Zendesk JWT with that secret using HS256.
4. Include the key ID in the kid header.
5. Include scope: "user", external_id, and exp in the JWT claims.
6. Return the Zendesk JWT through zdChatterAuthCallback in the Messaging SDK.

Token requirements:

• External ID: Use a non-empty external_id string of at most 255 characters. Exclude /, ?, #, %, whitespace, and control characters.
• Expiry: Set exp to an expiry time in Unix seconds.
• Verified details: Include optional name, email, and email_verified claims for verified email linking.
• Signing secret: Keep the secret on your server.

Verified email linking

Both methods use the same rules to link a verified email to a Zendesk end user during a Handoff.

When Ada initializes a Sunshine conversation with a verified email, it selects the Zendesk end user in this order:

1. Ada uses the Zendesk end user with the same external_id as the selected authentication method.
2. If no external ID match exists, Ada searches for a matching primary email.
3. If no email match exists, Ada creates a Zendesk end user with the external ID, name, and verified email.
4. If Ada cannot select or create an end user, it uses the authentication method’s external_id.

These rules apply to matching and creation:

• Email match: Ada matches primary emails only. It trims whitespace and converts emails to lowercase before matching.
• Eligible users: Ada requires exactly one exact match. It never links agents, admins, or ambiguous matches.
• Missing external ID: If the matching end user has no external ID, Ada sets it to the authentication method’s external_id.
• Different external ID: If the matching end user has a different external ID, Ada uses it without changing the Zendesk user. The conversation uses that Zendesk user’s history.
• Missing name: If no name is available when Ada creates an end user, it uses the verified email as the name.
• Permanent changes: Zendesk keeps the external IDs and end users that Ada sets or creates, even after you stop sending the email.

An initialized Sunshine conversation keeps its existing identity. Ada does not repeat matching for that conversation. If your Zendesk JWT already includes verified email claims, linking starts without another setting.

To stop verified email linking:

• For an identity token, omit verified_email from the next mint request.
• For a Zendesk JWT, remove email_verified from the next token.

Ada never uses email from your page, end user input, or Capture blocks to match or create Zendesk users. Neither method writes META email from these values. The email that your page or a Capture block sets stays unchanged.

If authentication fails

If authentication fails and no other identity mapping applies, the Handoff proceeds with an anonymous Sunshine user. Retry temporary identity lookup or Sunshine initialization failures to preserve the identified end user.

The sign-out reset() starts a new anonymous Ada session. See the identity token steps. A later authenticated Handoff can reuse an existing Zendesk user.

Use the Zendesk Messaging block

Add the Zendesk Messaging block to your Handoff dialog to route end users to live agents.

To add and configure the Zendesk Messaging block:

1. On the Ada dashboard, go to Config > AI AGENT > Handoffs, then create or select a Handoff to edit. For more information, see Manage Handoffs.

2. In the Handoff content, add Capture blocks to capture the end user’s name and email address. Capture blocks still set the requester name on the Zendesk ticket for a first escalation. They do not set a verified email or supply an email for linking Zendesk users. You can also capture their phone number.

   For the end user’s information to map to the correct fields on the Zendesk ticket, the variables that capture their name and email address must be named exactly:

   • name
   • email

3. Drag and drop the Zendesk Messaging block into the Handoff content, then configure the block using the following table as a guide:

   Standby Message	Support requests can occur both during business hours, or during off hours. Use this message to acknowledge the end user’s request and present information about response times. Craft a message for end users with helpful information, such as average wait times, or if agents are offline. Use the Scheduled block to help make this an even smoother experience.
   Department	This drop-down menu lists all the available support departments. Select the appropriate department for this Handoff.
   Zendesk Fields	Map your Zendesk fields to the block. Use these fields to enhance your support process: Present your agents with key end user details. Use Support triggers to route incoming tickets to the right team. You can map standard Zendesk fields such as Requester, Follower, Assignee, CCs, Share, Status, Type, Priority and Tags. These fields help ensure tickets are created with the right context and routed appropriately from the start. For more information, see Standard ticket fields in Zendesk’s documentation. Zendesk Field types Text, Number, Boolean, and Dropdown field types are all accepted. If you’re using the Dropdown field type, make sure you send the Tag value associated with the dropdown to Zendesk, to ensure that the value gets saved properly in your ticket.
   Tags	Use tags to identify the purpose of this Handoff. Tags attach to the Zendesk ticket automatically. Separate each tag with a comma.
   Keep same Sunshine Conversation	By default, when an end user ends the chat during a Handoff, Ada starts a new Sunshine conversation so your AI Agent regains control. Enable this setting to keep the existing Sunshine conversation instead — useful if you return control to Ada yourself (for example, by calling passControl through the Sunshine Conversations API) and need the sunshine_conversation_id to stay stable across the Handoff. Only enable this if your integration returns control to Ada via passControl. Otherwise, end users may remain connected to the agent after ending the chat instead of returning to your AI Agent.

4. Click Save.

Your Zendesk Handoff is ready to go.

Customer experience

The end user’s experience is seamless. Once they are handed over to the live support agent, the only thing that changes about their experience is who they are chatting with. AI Agent and live agent conversations remain in the same chat window.

End users can also minimize or close the chat window, regardless if it’s Ada’s or another brand’s chat environment, and expect their conversation history to persist; however, if they click the End Chat button, the conversation history clears.

Agent experience

When a Handoff to a live agent occurs through your AI Agent, the primary agent experience remains largely unchanged.

• Agents still handle all Live Agent conversations from their Zendesk Agent Workspace dashboard.
• Agents can also respond to end users asynchronously, and over an extended timeframe.

Transcripts show AI Agent messages with the channel set to “messaging”: