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.

Choose the Make API call step in an AI agent answer flow in place of the Transfer to agent step

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:

  1. In Admin Center, go to Apps and integrations > APIs > Conversations API
  2. Click Create API key
  3. Enter a name for the key in the Create new key dialog, then click Next
  4. 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:

  1. In Admin Center, go to Apps and integrations > 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 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
  8. 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.

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

    Make API call step in answer flow

    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.

  2. 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}}"
}
}
  3. 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.
  4. 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.

Custom field populated through API call

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
Powered by Zendesk