Zendesk Conversations

Integrate with Zendesk Conversations to enable bidirectional chat between your chatbot users and Zendesk agents. When a user requests a human agent or shows signs of frustration, the conversation is automatically escalated to a Zendesk agent. Messages are forwarded in both directions, and the session resolves when the agent releases control.

Connector Settings

Prerequisites

• A Zendesk account with Conversations Integration enabled
• API keys for Conversations Integration (key ID and secret)
• The Conversations Integration App ID

Zendesk-Side Setup

1. Create a Custom Integration

1. In Zendesk admin panel, navigate to Apps and integrations > Conversations integrations
2. Create a new Conversations Integration
3. Note the generated App ID — you will need it later

2. Generate API Keys

1. Go to Conversations integrations > Your new integration > API Keys
2. Create a new API key
3. Save the Key ID and Key Secret — the secret is only shown once

3. Configure a Webhook

1. Navigate to Conversations Integration > Your new integration > Edit

2. Fill in the webhook pointing to your connector's webhook URL (shown on the connector detail page after creation):

   POST https://your-app-domain.com/api/v1/connectors/{connector_id}/webhook

3. Select the following triggers:

   • Conversation message
   • Switchboard release control

Application-Side Setup

1. Go to Admin → Connectors
2. Click Add Connector
3. Select Zendesk (Conversations API) as the Integration Type
4. Fill in the following fields:

5. Select Workspaces to assign the connector to
6. Click Create connector
7. On the connector detail page, copy the auto-generated Webhook URL and use it when configuring the webhook in Zendesk

How It Works

Escalation

When a user requests a human agent or shows signs of frustration, the chatbot automatically:

1. Summarizes the conversation so far
2. Creates a user and conversation in Zendesk Conversations Integration
3. Sends the summary as the first message so the agent has context
4. Routes all subsequent user messages to the Zendesk agent

Message Forwarding

• User to agent — Messages sent by the user in the chat widget are forwarded to the Zendesk agent in real time
• Agent to user — Messages from the Zendesk agent are delivered to the user via the chat widget, including text, images, and file attachments

Waiting for an Agent

Between the escalation and the agent's first reply the widget shows a waiting card with a Cancel button. Zendesk's Conversations API exposes neither a queue position nor an agent typing indicator to a custom integration, so the card is the only progress the visitor can be shown.

Session Resolution

A live session ends in one of two ways:

• The agent resolves the conversation (releases switchboard control) — the visitor sees a notice that the session has ended.
• The visitor presses End (or Cancel while still waiting) — the app posts a notice into the Zendesk conversation so the agent knows why it went quiet.

Either way the AI resumes in the same chat with the full history — the earlier AI turns, the live conversation, and everything after it. The visitor can escalate again later, which reuses the chat's Zendesk visitor and conversation and posts a fresh summary into it, so the agent picks up the thread they already know.

Webhook Endpoint

POST /api/v1/connectors/{connector_id}/webhook

The endpoint accepts Zendesk Conversations Integration webhook events. Authentication is performed via the X-API-Key header, which must match the configured webhook secret.

Supported events:

Agent messages that arrive after a session has been resolved are ignored, so a late reply cannot land in a chat that is already back with the AI.