Workflow: Using an API call to transfer an AI agent conversation with metadata to a human agent

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

AI agents can collect important details from the customer, such as their name and email, before they escalate a ticket. With the Conversations Application Programming Interface (API) for 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.

Advanced developer workflow: This workflow requires familiarity with Sunshine Conversations APIs, Open Authorization (OAuth) management, switchboard architecture, and API development and debug tasks. Test thoroughly in a sandbox environment before production deployment.

Ensure you account for:

OAuth token refresh management and metadata size limits

Error responses, retry logic, and concurrent transfer management

Refer to the Sunshine Conversations Developer Docs for the latest API specifications

This article contains the topics below:

API escalation from the AI agent to a human agent

Step 1: Prepare your API call

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

API escalation from the AI agent to a human agent

The messaging feature uses a switchboard to manage conversations between systems during the customer journey. By default, the AI agent first handles the message from an end user, then transfers the conversation to the agent interface as needed, where a human agent takes over.

The Pass Control API call handles the handoff of the conversation from one system to another. This call allows you to include metadata, some of which Zendesk recognizes and uses to populate custom ticket fields.

Step 1: Prepare your API call

First, create your Sunshine Conversations API key. To create the API key:

In Admin Center, go to Apps and integrations > APIs > Conversations API

Click Create API key

Enter a name for the key in the Create new key dialog, then click Next

In the Copy shared secret dialog, click Copy in each field, then click Next:

The App ID, which identifies your Zendesk account

The Key ID, which, together with the secret key, are the credentials to authenticate JSON Web Tokens (JWTs) and API calls

The secret key, which is the authentication password

To create your connection to the Sunshine Conversations API:

In Admin Center, go to Apps and integrations > Connections > OAuth Clients

Click Create connection

Enter a name for the connection. You can't change this name after you create the connection.

Select the authentication type as Basic authentication

Enter the Key ID obtained previously for the Username

Enter the secret key obtained previously for the Password

Enter the allowed domain for the connection. This domain depends on what Uniform Resource Locator (URL) you use to call the API:

If you're a licensed Zendesk customer, use the below API host:
https://yoursubdomain.zendesk.com/sc

If you're not a licensed Zendesk customer, use the domain based on the regions specified in Sunshine Conversation Docs - Regions

Click Save to create the connection

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

If you already set up an AI agent, you're likely familiar with the transfer to agent option. If you need help with AI agent answers, see Create answers for common questions for the messaging feature Legacy.

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 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 with 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 account's switchboard ID and replace the switchboardIntegration value in the body JavaScript Object Notation (JSON) field. Contact Zendesk Customer Support for further help.

Click Done and test the AI agent before you publish

In this example, you populate a custom ticket field with the conversation ID. If you want to populate and include additional tags, add the key pattern "dataCapture.systemField.tags":"mytag1,mytag2".

Once the customer reaches the Make API call step in the AI agent response flow, the system creates a messaging ticket and populates the custom field with the information provided in the metadata.

You can implement this workflow for the AI agent through Web Widget for the messaging feature, mobile Software Development Kits (SDKs), or social messaging channels. For more information on how to use metadata for the messaging feature through API, see

Use metadata for the messaging feature with the Zendesk Web Widget and SDKs

Use metadata for the messaging feature with a Zendesk bot to send page data to a ticket