This article applies to AI agents - Essential and legacy AI agent functionality.

Using an AI agent, you can collect important details from the customer, such as their name and email, before escalating a ticket to a human agent. With the Conversations API, available in Zendesk Suite Professional and Enterprise plans, you can collect additional data beyond standard fields. This allows you to tailor the ticket creation process to fit your unique support workflows.

This article explains how to replace the default Transfer to agent step in an AI agent answer flow to collect all necessary information and transfer the conversation to an agent with a custom API call.

This article contains the following topics:

  • Understanding the API call used to transfer conversations from an AI agent to a human agent
  • Step 1: Prepare your API call
  • Step 2: Transfer the conversation with metadata to a human agent

Understanding the API call used to transfer conversations from an AI agent to a human agent

Zendesk messaging uses a switchboard to manage messages between different systems during the customer journey. By default, the Zendesk AI agent handles first the message that the end user sends. The AI agent can then transfer the conversation to the Zendesk support interface, where a human agent takes over.

Whether the transfer happens automatically through Zendesk services or a third party, the Pass Control API call is always in charge to hand off control of the conversation from one system to another. This call also allows you to include metadata, some of which Zendesk recognizes and uses to populate custom ticket fields. For more information on how to use metadata to include additional information such as ticket fields to tickets, see the article section: Metadata accepted by the Agent Workspace.

Step 1: Prepare your API call

Create your Sunshine Conversations API key

  1. In Admin Center, click Apps and integrations in the sidebar, then select APIs > Conversations API.
  2. Click Create API key.
  3. Enter an identifying name for the key in the Create new key dialog, then click Next.

  4. In the Copy shared secret dialog, click Copy for each ID and secret key to save it to your clipboard, then click Next.

    You should now have:

    • The App ID, which identifies your Zendesk account.
    • The Key ID, which, together with the secret key, are the credentials to authenticate JWTs and API calls.
    • The secret key, which is the authentication password.

For more information, see the article: Using the Conversations API keys.

Create your connection to the Sunshine Conversations API

  1. In Admin Center, click Apps and integrations in the sidebar, then select Connections > OAuth Clients.
  2. Click Create connection.
  3. Enter a name for the connection. 
    You can't change this name after you create the connection.
  4. Select the authentication type as Basic authentication.
  5. Enter the Key ID obtained previously for the Username.
  6. Enter the secret key obtained previously for the Password.
  7. Enter the allowed domain for the connection. This domain depends on what url you use to call the API:
    • If you are a licensed Zendesk customer, use the following API host:
      https://<subdomain>.zendesk.com/sc
    • If you are not a licensed Zendesk customer, use the domain based on the regions specified in this article:  Sunshine Conversation Docs - Regions
  8. Click Save to create the connection.

You are now ready to add the custom API call to the decision tree in your AI agent response flow.

Step 2: Transfer the conversation with metadata to a human agent

If you have already set up an AI agent to respond to your end users, you are likely familiar with how to set up AI agent responses with the default transfer to agent option. If you need more information to set up an AI agent answers, see the article: Creating answers for common customer questions in AI agents for messaging (Legacy).

Screenshot 2025-09-25 at 15.18.41.png

In your AI agent answer flow, locate the Transfer to agent step. Delete this step and replace it with the Make API call step.


In this example, you'll pass the current chat conversation ID as metadata. However, you can include any value, such as a variable collected from a form or data retrieved through an API call to a third-party service.

Enter the Make API call step details:

  • Request Method: POST
  • Endpoint URL : https://<allowed domain>/v2/apps/{{system.sunco.appId}}/conversations/{{system.sunco.conversationId}}/passControl
  • Body:
{
"switchboardIntegration": "<see bellow>",
"metadata": {
"dataCapture.ticketField.39320493167377":"{{system.sunco.conversationId}}"
}
}

Find your switchboard ID of your Zendesk account and replace the switchboardIntegration value in the body JSON field. If you require additional assistance, contact Zendesk Customer Support.

Here is what the API call will look like:

In this example, you populate a custom ticket field with the conversation ID. For more information on finding custom field IDs, see the article: Finding the field key or field ID for a custom field.

If you want to populate and include additional tags, you can include the key pattern "dataCapture.systemField.tags":"mytag1,mytag2". 

Once the user reaches the Make API call step in the AI agent response flow, Zendesk creates a messaging ticket. The custom field populates the information provided in the metadata.

You can apply this workflow with the AI agent through the Web Widget for messaging, mobile SDKs, or social messaging channels. To learn more about how to send agent messaging metadata from Web Widget and Zendesk SDKs through client-side APIs, see the articles below:

  • Using messaging metadata with the Zendesk Web Widget and SDKs
  • Using Messaging Metadata with a Zendesk bot to send page data to a ticket
Powered by Zendesk