> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/docs/channels/third-party/zendesk-sdk-deployment/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Zendesk SDK Deployment ## Overview You can use Zendesk Messaging SDKs to allow end users to interact with your AI Agent on their web or mobile devices. There are several other ways to do this, including using [Ada's SDKs](/docs/channels/chat/chat-configuration/installation), but this method is convenient if you already have an integration with Zendesk configured. ## Use cases Zendesk SDK deployment enables the following scenarios: * **Leverage existing Zendesk integration**: Deploy your AI Agent without additional infrastructure if you already use Zendesk for support. * **Web and mobile deployment**: Allow end users to interact with your AI Agent on both web and mobile devices using Zendesk's widgets and SDKs. * **Unified conversation experience**: Enable seamless [Handoffs](/docs/handoffs) between your AI Agent and human agents. ## Capabilities & configuration\[#understand-customer-experience-with-zendesk-messaging-sdks] The end user experience through Zendesk Messaging SDKs is very similar to Ada's default web experience in a lot of ways, with some exceptions. Here are some basics: * Customers can use the same conversation window to exchange messages with both your AI Agent and with human agents, with seamless [Handoffs](/docs/handoffs) to Zendesk Messaging in between. * Customers and agents can send files to each other. For information on how Zendesk validates files, see [Working with attachments](https://support.zendesk.com/hc/en-us/articles/4408821905434#topic_i32_zhh_3nb) at Zendesk's documentation. * After the customer has been handed off to an agent, the chat window is reserved for their conversation with the agent. Only the agent can disengage the conversation by marking the ticket as "solved." After this, depending on your organization's [trigger settings](#configure-settings-in-zendesk-admin-center), Zendesk automatically marks the ticket as "closed." Until the ticket is marked as "closed," any messages the customer sends go to the agent, not the AI Agent. The customer has to wait until the ticket is closed to be able to send messages to your AI Agent again. * You can use Zendesk's multi-instance routing feature. For more information, see [Connect Zendesk social channels to multiple AI Agents using Sunshine Conversations](/docs/channels/social/zendesk-social-integration). ### AI Agent behavior with Zendesk SDKs\[#understand-how-ada-features-work-with-zendesk-messaging-sdks] * The language your AI Agent sends messages in depends on the customer's browser settings. You can override the default language by setting the locale manually. For more information, see the [Set locale](https://developer.zendesk.com/api-reference/widget-messaging/web/core/#set-locale) section of Zendesk's Core messaging Web Widget API documentation. * Some [detailed reports](/docs/optimization/performance/reports/performance-reports) may not contain information about conversations that took place on Zendesk channels, depending on the data they require. * You can manage whether your AI Agent remembers customers between conversations in Agent Workspace. You can choose to retain conversation history, or to treat all customers as anonymous, with no saved previous conversation history. For more information, see the instructions in Zendesk's [troubleshooting](https://support.zendesk.com/hc/en-us/articles/4531075858458) documentation. This setting only applies to Zendesk's Web Widget, and not mobile; on mobile, Zendesk saves customer history by default. * You can control which website domains customers can see your Zendesk Web Widget on. For more information, see [Creating an allowlist for the Web Widget](https://support.zendesk.com/hc/en-us/articles/4500748175258-Installing-the-Web-Widget#topic_edv_xd5_2tb) at Zendesk's documentation. ## Quick start Deploy your AI Agent with Zendesk Messaging SDKs in a few steps. For detailed instructions, see [Implementation & usage](#set-up-zendesk-messaging-sdks-with-your-ai-agent). Complete the Sunshine Conversations integration with your AI Agent. Configure your Zendesk widget appearance in Zendesk Admin Center. Install the Zendesk widget on your website. Configure trigger settings and CSAT surveys in Zendesk Admin Center. Set up [Handoffs](/docs/handoffs) using HTTP Request blocks. ## Implementation & usage\[#set-up-zendesk-messaging-sdks-with-your-ai-agent] Setting up your AI Agent to work with Zendesk Messaging SDKs requires some work in Sunshine Conversations, in Zendesk, and finally in your own website. If you have any trouble with any portion of these procedures, don't hesitate to contact your Ada team for assistance. ### Prerequisites\[#before-you-begin] Before proceeding, do a quick check to see that you have the following: * Access to Zendesk Messaging (on Agent Workspace) * A subscription to Zendesk Suite Professional, Enterprise, Enterprise Plus, **or** a standalone Sunshine Conversations license add-on * Access to the Zendesk Conversations API through Zendesk Admin Center, so you can create API keys * A completed Sunshine Conversations integration with your AI Agent. For more information, see [Configure and use Sunshine Conversations](/docs/channels/social/sunshine-conversations-setup). * Your AI Agent's name configured in your Ada dashboard, so the AI Agent's name appears on messages in your widget and in Zendesk tickets. For more information, see [Customize your AI Agent's general settings](/docs/channels/chat/chat-configuration/appearance-settings#general). Additionally, contact your Ada team to make sure your AI Agent is ready for the next steps. There are some features you may need Ada staff to enable on your behalf that you can't proceed without. ### Zendesk widget configuration\[#configure-your-zendesk-widget] You can customize your web or mobile widgets in Zendesk Admin Center: * For information on how to customize how your widget looks, see [Configuring the widget launcher](https://support.zendesk.com/hc/en-us/articles/4500747797914-Configuring-the-appearance-of-the-Web-Widget#id_jnl_xtm_gnb) at Zendesk's documentation. * For more detailed information on additional settings you can change, see [Zendesk Web Widget and SDKs](https://developer.zendesk.com/api-reference/widget-messaging/introduction/) at Zendesk Developers' documentation. ### Zendesk widget installation\[#install-your-zendesk-widget-on-your-website] After configuring your Zendesk widget, you can install it on your website so customers can interact with it. * To install your widget on your website, find the installation script in your Admin Center and add it to your website's code. * Optionally, you can choose to enable your widget on your Zendesk Help Center. For installation instructions, see [Installing the Web Widget](https://support.zendesk.com/hc/en-us/articles/4500748175258-Installing-the-Web-Widget) at Zendesk's documentation. ### Zendesk Admin Center settings\[#configure-settings-in-zendesk-admin-center] In Zendesk Admin Center, you can configure two settings for your AI Agent's behavior: * You can set up triggers to automatically close tickets a certain amount of time after the agent marks them as "solved." For more information, see [Understanding and managing handback events](https://support.zendesk.com/hc/en-us/articles/4408824482586#topic_ux4_cqq_5pb) at Zendesk's documentation. * To collect customer satisfaction data, you can set up Zendesk's CSAT survey. For more information, see [About CSAT ratings in messaging](https://support.zendesk.com/hc/en-us/articles/4408832620570-About-CSAT-ratings-in-messaging) at Zendesk's documentation. Lastly, to allow your AI Agent to start interacting with customers, you have to connect your AI Agent with Zendesk. For more information, see [Connect your AI Agent with Zendesk Admin Center](/docs/handoffs/zendesk/zendesk-messaging#connect-your-ai-agent-with-zendesk-admin-center). ### Handoff configuration\[#set-up-handoffs-using-http-request-blocks] Instead of using Ada's usual [Handoff](/docs/handoffs) blocks, Zendesk Messaging SDKs use API requests to hand off end users to human agents. > **Note** > > When configuring handoffs using the HTTP Request block, make sure you > toggle on the **Count as Handoff** setting on the block to collect data > for your reports. For complete documentation on Sunshine Conversations' API, see [Metadata sent to Zendesk](https://docs.smooch.io/guide/switchboard/#metadata-sent-to-zendesk) at Sunshine Conversations' developer documentation. To get started, however, you can use these values using the variables with your AI Agent.
Name Value Notes
URL `https://api.smooch.io/v2/apps/{appId}/ conversations/{conversationId}/passControl`
appId `` * Sent in URL * Found in **Zendesk Admin Center** > **APIs** > **Conversations API**
conversationId `@sunshine_conversation_id` Sent in URL
Authorization `Basic @sunshine_basic_token` Sent in header
switchboardIntegration `“next”` Sent in body
metadata:first\_message\_id `@sunshine_first_message_id` * Sent in body * Sends first message of the most recent interaction, overriding default behavior of sending just the last 10 messages in the conversation
Here's an example of a completed handoff using an HTTP Request block: ![](/_fern-img/64099a2bbb92d868ac5560daad78b95a67a6ea977bec5cd8243fd33d7990411b.webp) In the above example, the request block also passes tags into Zendesk. This is how they look in the human agent's conversation with the customer: ![](/_fern-img/f081de884c068b43c0dbcb7dcaa107743acda7318b127d48c76333257cb8635c.webp) --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).