> 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. # Handoff scenarios ## Overview Ada supports multiple configurations for escalating Email conversations to human agents. Depending on your agent platform, channel setup (e.g., Email, Web [Chat](/docs/channels/chat), or both), and desired escalatory experience for human agents and end users, you can choose to create new tickets or update existing ones, and determine how human agents should respond. ## Common scenarios The following multi-channel scenarios cover typical handoff configurations. While many involve deciding whether to create a new ticket or case or update an existing one, others—such as using Email as an extension of [Chat](/docs/channels/chat)—focus on address and threading rules, and sometimes involve replying to existing tickets in your agent platform (e.g., Zendesk, Salesforce). Additional scenarios may apply depending on your specific implementation. ### Scenario 1: Email API–only implementation (no Direct Email)\[#email-api-only] Update existing tickets instead of creating new ones when every conversation starts from an existing ticket. The following flow applies to: * **Email-only implementations** * **Omni-channel implementations** (when using the Email API for the Email channel) To set this up, follow these steps: 1. Create a [Handoff](/docs/handoffs) flow in Ada with a rule that makes it trigger only for the Email channel. 2. Pass the originating ticket ID into Ada. In the webhook that passes inquiries to Ada via Email API, include the `ticket_ID` in the Email API metadata. For example: ``` { "name": "My Test" "subject": "CC Test", "reply_to": "john.smith@example.test", "text": "This is a test ticket body.", "reply_as": "help@example.test", "cc": ["alice@ventura-bank.test", "tim@ventura-bank.test"], "metadata" : { "ticket_id": "1001" } } ``` The variable name from the Email API metadata is saved in Ada with an Ada prefix to indicate its source. In the above example, the `ticket_id` is stored as `ada_email_webform_ticket_id`. 3. Follow the platform-specific instructions to configure how Ada updates tickets. #### Zendesk Add an [HTTP Request](/docs/handoffs/handoff-management/blocks/request-block) block to your [Handoff](/docs/handoffs) and call Zendesk's bulk update endpoint: 1. In the **HTTP Request** block's **URL** field, append the Ada-prefixed variable to the end of the endpoint URL. 2. Under **Headers**, add an **Authorization** token. 3. Under **Body Content**, link each relevant Zendesk field you want to update to its corresponding Ada variable. #### Salesforce Add a [Salesforce](/docs/channels/email/email-configuration/email-handoffs#salesforce) block to your [Handoff](/docs/handoffs). 1. In the **Salesforce** block, set the **Select Action** field to **Update Case**. 2. Link each relevant Salesforce field you want to update to its corresponding Ada variable. #### Other platforms If the platform provides an API endpoint for updating tickets, use an HTTP Request block together with the Ada-prefixed variable in the update request. #### FAQs #### Why can't customers update existing tickets if they implemented Ada's Email channel via Direct Email? When an end user emails Ada directly, there's no ticket/case yet in Zendesk or Salesforce. The conversation lives in Ada until a [Handoff](/docs/handoffs) is initiated. At escalation, Ada creates a new ticket/case (which receives a ticket ID). This ticket ID can be passed back to Ada only if the handoff block is configured to save it. #### Will \[Handoffs]\(../../../../handoffs/overview\.mdx) to Zendesk or Salesforce continue in the same thread? Can human agents reply from the same email address as the AI Agent? * **Zendesk**: No. Updating a ticket via an HTTP request does not support shared email address/thread behavior. That behavior is supported only by the [Zendesk Support](/docs/channels/email/email-configuration/email-handoffs#zendesk-support) block. * **Salesforce**: No. Replies to updated cases will start a new email thread, since human agents must use a different email address than the AI Agent. #### Any special considerations when using both Ada Email and Ada Chat? If human agents reply to a Zendesk ticket not created via the [Zendesk Support](/docs/channels/email/email-configuration/email-handoffs#zendesk-support) block, they must reply from an email address that is not configured as a channel on this AI Agent. This applies to: * **Chat handoffs**: [Zendesk Messaging](/docs/handoffs/zendesk/zendesk-messaging)/[Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing) block * **Email handoffs**: where the [Zendesk Support](/docs/channels/email/email-configuration/email-handoffs#zendesk-support) block is not used ### Scenario 2: Create new tickets with Direct Email, update existing ones with Email API If you are using **both Email API and Direct Email**, Ada can differentiate between the two and route [Handoffs](/docs/handoffs) accordingly. In this scenario, **Email API conversations update existing tickets**, while **Direct Email escalations create new tickets**. The [Handoff](/docs/handoffs) should be gated for the Email channel. It applies to: * **Email-only implementations** * **Omni-channel implementations** To set this up, follow one of these [Handoff](/docs/handoffs) flows: * **Single [Handoff](/docs/handoffs) flow gated for the Email channel, with conditionals**: If a conversation contains a specific variable, or it originates from: * Direct Email, then configure the handoff block to create a new ticket or case. * A Webform, then configure the handoff block to update an existing ticket or case. * **Two [Handoff](/docs/handoffs) flows, each gated by origin (Direct Email or Webform) or metadata (containing a specific variable)**: * One for updating existing tickets * One for creating new tickets Here's what this looks like in practice in different platforms: #### Zendesk * Use the [Zendesk Support](/docs/channels/email/email-configuration/email-handoffs#zendesk-support) or [Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing) block for conversations that should create a new ticket in Zendesk. * Use the [HTTP Request](/docs/handoffs/handoff-management/blocks/request-block) block for conversations that should update an existing ticket, following [these instructions](#email-api-only). **Notes:** * **Zendesk Support** block allows human agents to reply to Email handoffs using the same support address configured with the Email AI Agent; these replies will stay in the same thread. * **Zendesk Ticketing** block: With the [SMTP Connector](/docs/handoffs/zendesk/zendesk-smtp-connector) configured, human agents can reply using the same support email address in the same thread. Without the SMTP Connector, human agents must reply using a different support email address, and replies start a new thread. * Tickets updated via the **HTTP Request** block must be replied to from a different support address than the Email AI Agent. This can be the same address used for Chat handoffs. #### Salesforce * Use the [Salesforce](/docs/channels/email/email-configuration/email-handoffs#salesforce) block in your [Handoff](/docs/handoffs) * To create a new case, in the **Salesforce** block, set the **Select Action** field to **Create Case**. * To update an existing case, set the **Select Action** field to **Update Case**. > **Note** > > Regardless of the setting, human agents must reply from a different support email address than the Email AI Agent. Replies will go to end users in a new email thread. #### Other platforms * If the platform has an API endpoint for ticket creation, to create a ticket, use the [Email](/docs/channels/email/email-configuration/email-handoffs#email) or [HTTP Request](/docs/handoffs/handoff-management/blocks/request-block) block. * If the platform has an API endpoint for ticket updates, to update a ticket, use an [HTTP Request](/docs/handoffs/handoff-management/blocks/request-block) block. ### Scenario 3: Email as an extension of Web Chat In **omni-channel** configurations, Email is sometimes used as a fallback or follow-up method for [Chat](/docs/channels/chat) [Handoffs](/docs/handoffs). In these cases, human agents may be replying to existing tickets in your agent platform (e.g., Zendesk, Salesforce) over email. For any implementation that includes Ada's Email channel, it's important to plan which email addresses your human agent teams and your Email AI Agent will use to ensure correct threading behavior and avoid unexpected AI Agent re-entry. For more details, see this [decision table](/docs/handoffs/handoff-management#just-choosing-the-right-handoff-method). #### Key rules For Zendesk users: * Human agents can use the same support email address configured for the Email AI Agent to reply to messaging handoffs over email if: * The [Zendesk SMTP Connector](/docs/handoffs/zendesk/zendesk-smtp-connector) is configured AND * Human agents are either: * replying to tickets created by [Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing) OR * switching channels in Zendesk to reply via email to tickets created by the [Zendesk Messaging block](/docs/handoffs/zendesk/zendesk-messaging) *i.e. during agent offline hours* > **Note** > > Without the [Zendesk SMTP Connector](/docs/handoffs/zendesk/zendesk-smtp-connector) configured, human agents **must use a different support email address** than the one used by the Email AI Agent(BYOD) when continuing Web Chat conversations over email or starting new email conversations with end users that never route to Ada. #### Minimum requirements IF SMTP Connector isn't configured: Keep **at least one support email address that is not configured as an email channel** on this AI Agent. Use it for human agents replying to tickets created via Zendesk Ticketing, Salesforce Case, manually by agents, or any other path that is not the Zendesk Support block. The Email AI Agent's configured channels (any address set up via Bring Your Own Domain) can be reused for human-agent replies on tickets created by the Zendesk Support block — replies stay in the same thread on the same address the end user originally wrote to. For human-agent replies on all other ticket types, the address must be one that is not configured as an email channel on this AI Agent. #### Additional considerations If a human agent replies from the same address used by the AI Agent, but the ticket was **not** created by the Zendesk Support block, and SMTP Connector isn't configured, Ada will receive all end user replies to those human agent messages. In this case, the AI Agent may re-enter the conversation with no context, leading to a broken experience and loss of context for the end user. Without the [SMTP Connector](/docs/handoffs/zendesk/zendesk-smtp-connector) (and outside of the Zendesk Support block), using the same address can cause Ada to re-enter threads unexpectedly. #### Multi-domain SMTP requirements For AI Agents with inboxes on multiple BYOD domains: * The Zendesk SMTP Connector is configured per BYOD domain, not per inbox. * Inboxes that share a domain share the same SMTP configuration. * Each new BYOD domain that needs shared-thread human-agent replies requires its own SMTP setup. * Inboxes on a domain without an SMTP configuration fall back to the AI Agent's default Zendesk SMTP routing, which only works for the default email channel. See [Zendesk SMTP Connector](/docs/handoffs/zendesk/zendesk-smtp-connector) for setup steps. ## Combining handoff blocks across channels Depending on whether you want Email or [Chat](/docs/channels/chat) escalations (or both), you can mix and match [Handoff](/docs/handoffs) blocks as needed. #### Example 1: Live chat + same-thread email replies * **[Chat](/docs/channels/chat)**: Use [Zendesk Chat](/docs/handoffs/zendesk/zendesk-chat/zendesk-chat-handoff-setup#add-the-zendesk-live-agent-block-to-an-answer), [Zendesk Messaging](/docs/handoffs/zendesk/zendesk-messaging#use-the-zendesk-messaging-block), or [Zendesk Support](/docs/handoffs/zendesk/zendesk-support) * **Email**: Use [Zendesk Support](/docs/handoffs/zendesk/zendesk-support) > **Note** > > If using **Zendesk Support** for both Chat and Email, create two separate handoff flows, gated by channel. #### Example 2: Mixed live and async chat + same-thread email * **[Chat](/docs/channels/chat)**: * Use [Zendesk Messaging](/docs/handoffs/zendesk/zendesk-messaging#use-the-zendesk-messaging-block) or [Zendesk Support](/docs/handoffs/zendesk/zendesk-support) for live chat * Use [Zendesk Ticketing](/docs/handoffs/zendesk/zendesk-ticketing) for asynchronous fallback > **Note** > > Zendesk Ticketing replies must come from a different address if you don't have the SMTP Connector configured. * **Email**: Use [Zendesk Support](/docs/channels/email/email-configuration/email-handoffs#zendesk-support) or [Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing) > **Note** > > With the [SMTP Connector](/docs/handoffs/zendesk/zendesk-smtp-connector) configured, Zendesk Ticketing replies can use the same address as the Email AI Agent and continue in the same thread. Without the SMTP Connector, replies must use a different address and will start a new thread. > **Note** > > If using [Zendesk Support](/docs/channels/email/email-configuration/email-handoffs#zendesk-support) for both Chat and Email you must configure two handoff flows, each gated with a rule for the channel. #### Example 3: All channels escalate over email * **[Chat](/docs/channels/chat)**: Use [Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing) * **[Voice](/docs/channels/voice)**: Use [Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing) * **Email**: Use [Zendesk Support](/docs/channels/email/email-configuration/email-handoffs#zendesk-support) or [Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing) > **Note** > > With the [SMTP Connector](/docs/handoffs/zendesk/zendesk-smtp-connector) configured, [Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing) replies can use the same address as the Email AI Agent and continue in the same thread. Without the SMTP Connector, replies must use a different address and start a new thread. [Zendesk Support](/docs/channels/email/email-configuration/email-handoffs#zendesk-support) supports same-thread, same-address replies by default. ### Best practices for configuring handoff blocks * Use system variables (purple) in all [Handoff](/docs/handoffs) blocks * Common variables include: * `email` * `name`, `first_name`, `last_name` (generated from email) * `ada_email_subject` (from email subject line) * `email_attachments`: Required only for the [Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing), [Salesforce](/docs/channels/email/email-configuration/email-handoffs#salesforce), and [Email](/docs/channels/email/email-configuration/email-handoffs#email) blocks * [Zendesk Support](/docs/channels/email/email-configuration/email-handoffs#zendesk-support) passes attachments by default #### Examples Here are some example configurations for common email handoff scenarios, showing how to apply best practices in different situations. #### Send to original sender only ![](/_fern-img/fc0d3fe31e9bdb55355e77d9555ff5bd63caf3d610063de90ab7ea2c09f104c2.webp) #### Include CC list ![](/_fern-img/9bd4fc136d374ae8436e0792d8c7f4790d0c30d09e274b73489fc3e64bf4838a.webp) > **Note** > > In this example, `CC_list` is a custom Zendesk field to store CC'd participant email addresses. #### Track as handoff ![](/_fern-img/0f5530251bbfd097c7856045baf3574be019e7f964a4ebe0c61a51320352dae0.webp) > **Tip** > > Enable the **Track as handoff** setting to ensure proper reporting. ### Handling original tickets from Email API Here's a common workflow for handling original tickets from the Email API: 1. Customer fills out Webform that causes a ticket to be created 2. Ticket automation calls the Email API 3. Callonversation is handed off 4. Ada can either: * Update the ticket * Create a new one > **Note** > > The ability to update depends your agent platform and the APIs available to it 5. Optional: Automation in agent platform closes tickets after five days ### Additional best practices * Create a dedicated [Handoff](/docs/handoffs) flow for Email, gated by `channel = Email` * Use conditionals and Ada variables to decide when to create vs. update a ticket (ability to update depends your agent platform) * Choice of handoff block depends on: * Preferred handoff threading experience for end user * Whether SMTP Connector is configured or not ## Related features Explore additional Email Handoff and configuration options. * [Email handoffs](/docs/channels/email/email-configuration/email-handoffs): Configure Handoff blocks for your Email channel. * [Handoffs](/docs/handoffs): Learn about Handoff capabilities across all channels. * [Zendesk SMTP Connector](/docs/handoffs/zendesk/zendesk-smtp-connector): Enable shared email addresses between your AI Agent and human agents. * [Multiple participant conversations](/docs/channels/email/email-configuration/multiple-participant-conversations): Handle emails with CCs and multiple recipients during Handoffs. * [Attachment handling](/docs/channels/email/email-configuration/email-handoffs/attachment-handling): Pass email attachments to human agents during Handoffs. --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).