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

Session Resolution

When the Zendesk agent resolves the conversation (releases switchboard control), the user is notified that the human support session has ended and user should start a new conversation.

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: