Zendesk Escalations

​

Overview

​

Video Walkthrough

​

Requirements

• Active Zendesk account
• Zendesk integration connected (see Integration Setup below)
• API token with ticket creation permissions
• Appropriate support group assignments

​

Setup Instructions

​

Step 1: Connect Zendesk Integration

​

Step 2: Create Escalation Path

1. Navigate to Agents → Your Agent → Escalations
2. Click “Create Escalation Path”
3. Fill in the basic information:
   • Name: Descriptive name (e.g., “Zendesk Support Tickets”)
   • Platform: Select “Zendesk”
   • Platform Integration: Choose your connected Zendesk account

​

Step 3: Configure Zendesk Settings

• Default Priority: normal, low, high, or urgent
• Default Type: question, incident, problem, or task
• Tags (optional): Auto-apply tags (e.g., “ai-escalation”, “chatbot”)
• Group ID (optional): Assign to specific support group
• Subject Template (optional): Custom ticket subject format

​

Step 4: Save Configuration

​

Step 5: Configure Webhook (Required for Agent Replies)

1. In Zendesk, go to Admin Center → Apps and integrations → Webhooks
2. Click “Create webhook”
3. Set the events as “Comment Created” and “Status Changed”.
4. Configure:
   • Endpoint URL: Copy the webhook URL shown on your escalation path
   • Request method: POST
   • Request format: JSON
   • Custom header: Add X-SupportUnicorn-Webhook with the signature token shown on your escalation path
5. Click “Create webhook”

​

Step 6: Use a Separate API User (Important)

1. In Zendesk, create a new agent or admin user (e.g., “Support Unicorn Bot”)
2. Generate an API token for this user
3. Use this user’s email and API token in your escalation path configuration
4. Run rake zendesk:populate_user_ids to store the API user ID

​

Configuration Options

​

Priority Levels

• Low: General inquiries, non-urgent questions
• Normal: Standard support requests (default)
• High: Important issues needing prompt attention
• Urgent: Critical issues requiring immediate response

​

Ticket Types

• Question: General customer inquiries
• Incident: Service disruptions or errors
• Problem: Root cause of multiple incidents
• Task: Work items or requests

​

Subject Template

[AI Escalation] {{customer_name}} - {{escalation_reason}}

​

Available Variables

• {{customer_name}}: Customer’s name or identifier
• {{channel_name}}: Communication channel
• {{escalation_reason}}: Why escalated
• {{agent_name}}: AI agent name
• {{timestamp}}: When escalated

​

Ticket Content

• Escalation Reason: Why the conversation was escalated
• Channel: Where the conversation took place (Live Chat, SMS, etc.)
• Full Transcript: Complete conversation history
• Customer Information: Name, email, identifier
• Timestamp: When escalation occurred

​

Tags

• ai-escalation: Identifies AI-escalated tickets
• chatbot: Originated from chatbot
• channel-livechat / channel-sms: Indicates channel
• billing, technical, sales: Topic categories

​

Group Assignment

1. Find your group ID in Zendesk:
   • Go to Admin → People → Groups
   • Click on a group
   • Group ID is in the URL: .../groups/[GROUP_ID]/edit
2. Enter the Group ID in escalation settings

• Tier 1 Support: 123456
• Billing Team: 234567
• Technical Support: 345678

​

How It Works

1. Ticket Created: New ticket created in Zendesk with full conversation history
2. AI Pauses: AI agent stops responding to the customer
3. Agent Assigned: Ticket routed per Zendesk rules
4. Context Included: Full conversation transcript in ticket description
5. Notification Sent: Agent receives Zendesk notification
6. Human Response: Agent responds through Zendesk
7. Reply Routed: Zendesk webhook sends the reply back to Support Unicorn
8. Customer Receives: Reply delivered to customer on original channel (live chat, SMS, or WhatsApp)

​

Reply Flow (Agent → Customer)

1. Zendesk fires the webhook to your Support Unicorn endpoint
2. Support Unicorn matches the ticket ID to the original conversation
3. The reply is routed back to the customer via their original channel:
   • Live Chat: Delivered via WebSocket in real-time
   • SMS: Sent via Twilio
   • WhatsApp: Sent via Twilio

​

Customer Follow-up Messages

1. The message is stored in the conversation
2. It is automatically added as a public comment on the Zendesk ticket
3. The Zendesk agent sees it in real-time

​

Managing Zendesk Escalations

​

Test Connection

1. Navigate to Agents → Your Agent → Escalations
2. Find your Zendesk escalation path
3. Click “Test Connection”
4. Verify test ticket appears in Zendesk

​

Activate/Deactivate

​

Edit Settings

1. Navigate to Agents → Your Agent → Escalations
2. Click the Zendesk escalation path
3. Update configuration
4. Click “Save Changes”

​

Best Practices

1. Clear Tagging: Use consistent tags for reporting and filtering
2. Appropriate Priority: Set realistic default priorities
3. Group Assignment: Route to appropriate teams
4. Subject Templates: Include key information in subject
5. SLA Monitoring: Track response times for escalated tickets
6. Regular Review: Analyze escalation patterns to improve AI

​

Example Use Cases

​

Use Case 1: Billing Issues

• Priority: High
• Type: Question
• Tags: ai-escalation, billing, urgent
• Group: Billing Team (ID: 234567)
• Trigger: Keywords (“refund”, “charge”, “billing”)

​

Use Case 2: Technical Problems

• Priority: Normal
• Type: Incident
• Tags: ai-escalation, technical, bug
• Group: Technical Support (ID: 345678)
• Trigger: Keywords (“error”, “broken”, “not working”)

​

Use Case 3: General Escalations

• Priority: Normal
• Type: Question
• Tags: ai-escalation, general
• Group: Tier 1 Support (ID: 123456)
• Trigger: Message count > 5

​

Using in Procedures

For billing issues:
{{escalate:escal_zendesk_billing}}
I've created a support ticket for our billing team. They'll contact you within 24 hours.

​

Troubleshooting

​

Tickets Not Being Created

• Verify Zendesk integration is connected and active
• Check API token has ticket creation permissions
• Ensure escalation path is activated
• Test connection using “Test Connection” button
• Review Zendesk API logs for errors

​

Tickets Created in Wrong Group

• Verify Group ID is correct
• Check that group exists in Zendesk
• Ensure API user has permission to assign to group
• Review Zendesk automation rules (may override)

​

Tags Not Applied

• Verify tag syntax (comma-separated, no special chars)
• Check Zendesk tag permissions
• Ensure tags don’t conflict with Zendesk triggers

​

Agent Replies Not Reaching Customer

• Webhook not configured: Ensure you completed Step 6 (webhook setup in Zendesk). Without it, no data reaches Support Unicorn when agents reply.
• Same user for API and agent: If the API user ID matches the replying agent’s ID, replies are silently filtered as “webhook loops”. Use a separate service account for the API credentials (see Step 7).
• Webhook URL incorrect: Verify the webhook URL in Zendesk matches the one shown on your escalation path.
• Trigger not firing: Ensure the Zendesk trigger conditions match (public comment, by agent, correct tags).
• Check server logs: Look for Skipping comment: posted by API user — this means the API user ID matches the agent. Look for No conversation found for Zendesk ticket — this means the ticket ID doesn’t match any escalated conversation.

​

”Failed to connect to human agent” Error

• No stale Slack escalation paths are active on the same agent
• The agent’s highest-priority active escalation path is the Zendesk one

​

Missing Conversation Context

• Verify escalation template includes transcript
• Check webhook configuration
• Review escalation service logs

​

Next Steps