> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Zendesk Messaging ## Overview\[#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. > **Note** > > > > > > > > > >
> ![](/_fern-img/f5435222735a5b23e5bb763ca4ccb5daee14dc843086db11d19d699791904fce.webp) > > This topic is about Zendesk Messaging. If you're looking for information about Zendesk Chat, please see > [Zendesk Chat Handoff usage](/docs/handoffs/zendesk/zendesk-chat/zendesk-chat-handoff-usage). >
### What is asynchronous chat?\[#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\[#requirements] Ada Glass for Zendesk Messaging requires that your Zendesk and Ada accounts have the following products enabled and configured: > **Info** > > If you're migrating from Zendesk Chat to Zendesk Messaging, inform your Customer Success Consultant (CSC). Specific configuration changes must be made during the migration process to ensure a smooth transition. * **Zendesk** * [Sunshine Conversations](https://developer.zendesk.com/documentation/custom-data/conversations/what-is-sunshine-conversations-/) * Channel: [Web Messenger](https://docs.smooch.io/guide/web-messenger/) * [Zendesk Agent Workspace](https://support.zendesk.com/hc/en-us/articles/4408821259930-About-the-Zendesk-Agent-Workspace) * **Ada** * Ada Glass for Zendesk Messaging * [Sunshine Conversations channel integration](/docs/channels/social/sunshine-conversations-setup) ## Capabilities & configuration Zendesk Messaging Glass provides [Handoff](/docs/handoffs) 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](#implementation--usage) for detailed instructions. #### Connect your Zendesk account Authorize your Zendesk subdomain via Config > Apps > Zendesk. See [Connect your Zendesk account](/docs/handoffs/zendesk#connect-your-zendesk-account). #### Connect Sunshine Conversations Connect your Sunshine Conversations app to Ada. On the Ada dashboard, go to Config > CHANNELS > Social, click Configure beside Sunshine Conversations, and connect your app. See [Sunshine Conversations setup](/docs/channels/social/sunshine-conversations-setup#connect-sunshine-conversations-with-ada). #### Configure Zendesk Messaging Glass Navigate to Handoffs > Integrations and configure Zendesk Messaging with the connected subdomain. #### Enable multi-conversation support In Zendesk Admin Center, turn on multi-conversations so end users can cleanly end a Handoff. #### Create an end conversation trigger Set up a Zendesk trigger to automatically end agent conversations when tickets are solved. #### Set your AI Agent as the default switchboard integration In Zendesk Admin Center, set your AI Agent as the default for all channels so end users reach it first. #### Add the Zendesk Messaging block Add and configure the Zendesk Messaging block in your Handoff dialog. ## Implementation & usage Configure Zendesk Messaging Glass and set up the [Handoff](/docs/handoffs) 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](/docs/handoffs/zendesk#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](/docs/channels/social/sunshine-conversations-setup#connect-sunshine-conversations-with-ada) 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**. > **Note** > > Turning on multi-conversations for one messaging channel enables it across all web, iOS, and Android messaging channels. Multi-conversation support can be enabled before or after connecting your Zendesk account. The Zendesk guide also covers removing the "new conversation" button from channels where it is not wanted; for details, see [Allowing multiple conversations for your end users](https://support.zendesk.com/hc/en-us/articles/8008427696410-Allowing-multiple-conversations-for-your-end-users) in Zendesk's documentation. ### 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. > **Tip** > > Zendesk may change their functionality without notice. For more details and the most up to date information about creating triggers, refer to Zendesk's guide [Creating triggers for automatic ticket updates and notifications](https://support.zendesk.com/hc/en-us/articles/4408886797466-Creating-triggers-for-automatic-ticket-updates-and-notifications). **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. > **Note** > > End users on web or mobile can release themselves from an agent conversation by clicking the **X** at the top of the chat window. ### Set Ada as the default switchboard integration\[#connect-your-ai-agent-with-zendesk-admin-center] 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. > **Warning** > > Set your AI Agent as the default for **all channels**. Setting it as the default for a single channel or integration only — for example, the Ada web integration — is **not sufficient**. **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](https://support.zendesk.com/hc/en-us/articles/5064149334426) 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](/docs/handoffs), so agents see the correct profile and ticket history. Identity tokens also keep Ada conversations available across devices. | Setup or capability | Ada identity token, recommended | Zendesk JWT | | ------------------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Server action | Request a token from Ada's Platform API | Sign a Zendesk JWT with HS256 | | Signing secret shared with Ada | None | Zendesk signing key ID and secret | | Additional Zendesk setup | Not needed | Create a **Messaging authentication** key | | SDK setting | [`identityToken`](/messaging/web/sdk-api-reference#identitytoken) | [`zdChatterAuthCallback`](/messaging/web/sdk-api-reference#zdchatterauthcallback) | | Zendesk user key | Platform API `external_id`, preserving original case | Zendesk JWT `external_id` claim | | Verified email linking | Mint request `verified_email` | `email` and boolean `email_verified: true` | | New user name | Request `name`, then profile `first_name` and `last_name` | JWT `name` | | Token lifetime | Single use, 15 minutes after minting | Valid `exp` at verification | | Identifies the Ada session | Yes | No | | Supported platforms | Web, iOS, Android, React Native | Web, iOS, Android, React Native | | Both methods present | Takes precedence | Applies when no preceding identity mapping succeeds | 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](/reference/end-users/overview). 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](/reference/auth-tokens/overview), using the returned `end_user_id`. Include optional `verified_email` and `name` fields for [verified email linking](#verified-email-linking). 3. Pass the token to the SDK as [`identityToken`](/messaging/web/sdk-api-reference#identitytoken). 4. When the end user signs out, call `reset()`. See the [identity token setup guide](/messaging/identity/getting-started) for web and mobile code. #### How Ada stores verified details Ada encrypts the optional values in the token and stores them encrypted on the session's end user after exchange. * **Storage window**: Ada uses the values only within 7 days after exchange. Session refresh does not extend this window. * **Successful Handoff**: Ada deletes the values after the first Zendesk Messaging Handoff uses them and Sunshine initialization succeeds. * **Failed initialization**: Ada keeps the values for a retry within the storage window. * **Unused values**: After the window ends, Ada deletes unused values at the next Handoff or token exchange. * **New exchange**: A new exchange replaces previous values, including exchanges without optional values or on another device. * **No verified email**: Without `verified_email`, the Handoff uses the Platform API identity mapping without email linking. A `name` alone does not enable linking. See [optional verified details](/reference/auth-tokens/overview#optional-verified-details) for validation, name fallback, and display rules. #### 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`](/messaging/web/sdk-api-reference#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](#verified-email-linking). * **Signing secret**: Keep the secret on your server. #### How Ada verifies and stores the Zendesk JWT Once Ada configures the signing secret, the SDK requests the Zendesk JWT during startup, before the [Handoff](/docs/handoffs). * **Key ID**: Ada checks `kid` against the configured key ID. Without a configured key ID, Ada verifies the signature without checking `kid`. * **Storage**: After successful verification, the server stores the identity and its validity window on the end user record. Browser metadata cannot supply or change these values. * **Renewal**: Each successful startup check renews the window for 24 hours. Zendesk Messaging does not schedule automatic renewal during an open session. * **Verified email**: Ada uses `name` and `email` for display and linking only with `email` and boolean `email_verified: true`. Otherwise, Ada uses only `external_id`. With a verified email, Ada applies these display rules: * Ada writes META `jwt_name` and `jwt_email`, as it does for Zendesk Chat. These values appear in the Ada dashboard and reach the end user's browser. * If a value is missing or empty, Ada clears its previous display copy only when it still matches the value Ada wrote. * Ada updates META `name` only when it is empty or still equals the previous Zendesk JWT's name. * When Ada clears the identity or detects expiry, it clears display copies that still match the values Ada wrote. #### Verified email linking Both methods use the same rules to link a verified email to a Zendesk end user during a [Handoff](/docs/handoffs). > **Warning** > > Ada trusts the verified email you send. Verify ownership before you send it. > A wrong email links the conversation to another person's Zendesk user. > The agent then sees that person's profile and ticket history. > Ada writes to your Zendesk account and does not undo these changes. 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](/docs/handoffs) 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](#use-an-ada-identity-token). A later authenticated Handoff can reuse an existing Zendesk user. ### Use the Zendesk Messaging block Add the Zendesk Messaging block to your [Handoff](/docs/handoffs) 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](/docs/handoffs/handoff-management). 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. > **Warning** > > 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. > **Tip** > > Craft a message for end users with helpful information, such as average wait times, or if agents are offline. Use the [Scheduled block](/docs/handoffs/handoff-management/blocks/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](https://support.zendesk.com/hc/en-us/articles/4408819011354-Recipe-Routing-messaging-tickets-using-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](https://support.zendesk.com/hc/en-us/articles/203661506#topic_drw_ft1_3nb) 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. > **Note** > > 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. > **Note** > > 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](/docs/handoffs) 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": --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).