Zendesk Messaging MCP Server

Create a powerful Model Context Protocol (MCP) server for Zendesk Messaging in minutes with our AI Gateway. This guide walks you through setting up seamless messaging and chat integration with enterprise-grade security and instant OAuth authentication.

About Zendesk Messaging API

Zendesk Messaging provides modern conversational experiences across web, mobile, and social channels. The API enables you to manage conversations, automate responses, integrate bots, and deliver personalized messaging experiences at scale.

Key Capabilities

• Conversation Management: Real-time chat and messaging
• Channel Integration: Web, mobile, social messaging
• Bot Framework: AI and automation integration
• Rich Messaging: Media, cards, quick replies
• Agent Tools: Routing, shortcuts, canned responses
• Customer Context: Profile and history access
• Proactive Messaging: Targeted campaigns
• Analytics: Conversation metrics and insights

API Features

• Conversations API: Message management
• Sunshine Conversations: Omnichannel platform
• OAuth 2.0: Secure authentication
• Webhooks: Real-time events
• Bot Integration: AI assistant support
• Rich Content: Structured messages
• File Handling: Media attachments
• Real-time Updates: WebSocket support

What You Can Do with Zendesk Messaging MCP Server

The MCP server transforms Zendesk Messaging API into a natural language interface, enabling AI agents to:

Conversation Management

• Message Operations

  • "Send message to customer"
  • "Reply with product information"
  • "Transfer chat to sales team"
  • "Close conversation"

• Conversation Search

  • "Find active conversations"
  • "Show unassigned chats"
  • "List conversations from VIP"
  • "Search messages about refunds"

• Message Actions

  • "Mark conversation as urgent"
  • "Add internal note"
  • "Set conversation tags"
  • "Schedule follow-up"

Bot Integration

• Bot Responses

  • "Create greeting bot flow"
  • "Set up FAQ bot"
  • "Configure intent detection"
  • "Build conversation tree"

• Automation Rules

  • "Auto-assign by topic"
  • "Route to department"
  • "Trigger based on keywords"
  • "Escalate to human agent"

• Bot Analytics

  • "Track bot performance"
  • "Measure deflection rate"
  • "Analyze handoff reasons"
  • "Monitor satisfaction"

Channel Management

• Web Widget

  • "Configure chat widget"
  • "Set business hours"
  • "Customize appearance"
  • "Enable proactive chat"

• Mobile SDK

  • "Configure mobile messaging"
  • "Set push notifications"
  • "Enable offline messaging"
  • "Sync user identity"

• Social Channels

  • "Connect WhatsApp"
  • "Add Facebook Messenger"
  • "Configure Instagram DM"
  • "Enable Apple Business Chat"

Agent Experience

• Workspace Tools

  • "Access customer profile"
  • "View conversation history"
  • "Use canned responses"
  • "Insert help articles"

• Collaboration

  • "Invite agent to chat"
  • "Transfer with context"
  • "Add private notes"
  • "Share conversation link"

• Shortcuts

  • "Apply macro"
  • "Use text expansion"
  • "Insert emoji"
  • "Quick actions"

Proactive Messaging

• Campaign Creation

  • "Send targeted message"
  • "Create welcome campaign"
  • "Launch promotion"
  • "Schedule announcement"

• Audience Targeting

  • "Target by behavior"
  • "Segment by location"
  • "Filter by attributes"
  • "Use custom events"

• Message Templates

  • "Create campaign template"
  • "Design rich cards"
  • "Add quick replies"
  • "Include media"

Analytics & Reporting

• Conversation Metrics

  • "Show response times"
  • "Track resolution rates"
  • "Measure satisfaction"
  • "Monitor volume trends"

• Agent Performance

  • "Track handling time"
  • "Measure concurrency"
  • "Show activity stats"
  • "Calculate efficiency"

• Channel Analytics

  • "Compare channel usage"
  • "Track channel costs"
  • "Measure effectiveness"
  • "Optimize channel mix"

Rich Messaging

• Content Types

  • "Send image carousel"
  • "Create action buttons"
  • "Build list picker"
  • "Design time picker"

• Interactive Elements

  • "Add quick replies"
  • "Create forms"
  • "Build surveys"
  • "Enable payments"

• Media Handling

  • "Upload images"
  • "Share documents"
  • "Send videos"
  • "Handle voice messages"

Workflow Integration

• Ticket Creation

  • "Convert to ticket"
  • "Link conversation"
  • "Sync updates"
  • "Maintain context"

• CRM Integration

  • "Sync customer data"
  • "Update profiles"
  • "Track interactions"
  • "Log activities"

• Custom Integration

  • "Trigger webhooks"
  • "Call external APIs"
  • "Update systems"
  • "Sync data"

Prerequisites

• Access to Cequence AI Gateway
• Zendesk Suite with Messaging
• Admin permissions
• OAuth application credentials

Step 1: Create Zendesk OAuth Application

1.1 Access Admin Center

1. Log in to Zendesk
2. Go to Admin Center > Apps and integrations
3. Select APIs > Zendesk API
4. Click OAuth Clients tab

1.2 Create OAuth Client

1. Click Add OAuth Client
2. Fill in details:
   • Client Name: "AI Gateway Messaging MCP"
   • Company: Your company name
   • Description: "Messaging and chat integration"
   • Redirect URLs:

     https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

1.3 Configure Permissions

1. Set client type to Confidential
2. Select messaging scopes:
   • messaging:read - Read conversations
   • messaging:write - Send messages
   • chat:read - Access chat data
   • chat:write - Manage chats

1.4 Save Credentials

1. Click Save
2. Copy Client ID
3. Copy Client Secret
4. Note your Subdomain

Step 2-4: Standard Setup

Follow standard steps to access AI Gateway, find Zendesk Messaging API, and create MCP server.

Step 5: Configure API Endpoints

1. Base URL: https://{subdomain}.zendesk.com/api/v2
2. Sunshine API: https://{subdomain}.zendesk.com/api/sunshine/conversations
3. Select endpoints:
   • Conversations endpoints
   • Messages endpoints
   • Channels endpoints
4. Click Next

Step 6: MCP Server Configuration

1. Name: "Zendesk Messaging"
2. Description: "Chat and messaging platform"
3. Configure production mode
4. Click Next

Step 7: Configure Authentication

1. Authentication Type: OAuth 2.0
2. Authorization URL:

   https://{subdomain}.zendesk.com/oauth/authorizations/new

3. Token URL:

   https://{subdomain}.zendesk.com/oauth/tokens

4. Enter Client ID and Secret
5. Select required scopes

Available Zendesk Messaging OAuth Scopes

Messaging Scopes

• messaging:read

  • View conversations
  • Read messages
  • Access metadata
  • See participants

• messaging:write

  • Send messages
  • Update conversations
  • Manage participants
  • Handle media

Chat Scopes

• chat:read

  • View chat history
  • Access visitor info
  • Read departments
  • See agents

• chat:write

  • Send chat messages
  • Transfer chats
  • Update visitor data
  • Manage routing

Recommended Scope Combinations

For Messaging Agents:

messaging:read
messaging:write
chat:read
chat:write

For Bot Integration:

messaging:read
messaging:write
users:read
organizations:read

Step 8-10: Complete Setup

Configure security, choose deployment, and deploy.

Using Your Zendesk Messaging MCP Server

With Claude Desktop

{
  "servers": {
    "zendesk-messaging": {
      "url": "your-mcp-server-url",
      "auth": {
        "type": "oauth2",
        "client_id": "your-client-id"
      }
    }
  }
}

Natural Language Commands

• "Send welcome message to new chat visitor"
• "Transfer conversation to sales team"
• "Show all active conversations"
• "Create auto-response for business hours"
• "Send product catalog carousel"

API Integration Example

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'oauth2',
    token: 'access-token'
  }
});

// Send a message
const message = await mcpClient.zendesk.messaging.sendMessage({
  conversationId: 'conv_123',
  message: {
    type: 'text',
    text: 'Hello! How can I help you today?',
    metadata: {
      sentBy: 'agent',
      agentId: currentAgentId
    }
  }
});

// Send rich message with quick replies
const richMessage = await mcpClient.zendesk.messaging.sendMessage({
  conversationId: 'conv_123',
  message: {
    type: 'structured',
    content: {
      type: 'quick_replies',
      text: 'What would you like help with?',
      quick_replies: [
        {
          text: 'Track Order',
          payload: 'TRACK_ORDER',
          action: 'postback'
        },
        {
          text: 'Return Item',
          payload: 'RETURN_ITEM',
          action: 'postback'
        },
        {
          text: 'Contact Support',
          payload: 'CONTACT_SUPPORT',
          action: 'postback'
        }
      ]
    }
  }
});

// Send carousel message
const carousel = await mcpClient.zendesk.messaging.sendMessage({
  conversationId: 'conv_123',
  message: {
    type: 'carousel',
    items: [
      {
        title: 'Premium Package',
        description: 'Our most popular plan',
        image_url: 'https://example.com/premium.jpg',
        buttons: [
          {
            text: 'Learn More',
            url: 'https://example.com/premium',
            type: 'web_url'
          },
          {
            text: 'Select Plan',
            payload: 'SELECT_PREMIUM',
            type: 'postback'
          }
        ]
      },
      {
        title: 'Business Package',
        description: 'Perfect for growing teams',
        image_url: 'https://example.com/business.jpg',
        buttons: [
          {
            text: 'Learn More',
            url: 'https://example.com/business',
            type: 'web_url'
          },
          {
            text: 'Select Plan',
            payload: 'SELECT_BUSINESS',
            type: 'postback'
          }
        ]
      }
    ]
  }
});

// Create bot flow
const botFlow = await mcpClient.zendesk.messaging.createBotFlow({
  name: 'Order Status Bot',
  trigger: {
    type: 'intent',
    value: 'check_order_status'
  },
  steps: [
    {
      id: 'greeting',
      type: 'message',
      content: {
        text: "I'll help you check your order status. What's your order number?"
      }
    },
    {
      id: 'collect_order',
      type: 'collect',
      variable: 'order_number',
      validation: {
        pattern: '^[A-Z]{2}[0-9]{6}$',
        error_message: 'Please enter a valid order number (e.g., AB123456)'
      }
    },
    {
      id: 'lookup_order',
      type: 'webhook',
      url: 'https://api.example.com/orders/{{order_number}}',
      method: 'GET'
    },
    {
      id: 'show_status',
      type: 'message',
      content: {
        text: 'Your order {{order_number}} is {{webhook.status}} and will arrive on {{webhook.delivery_date}}.'
      }
    }
  ]
});

// Configure proactive messaging campaign
const campaign = await mcpClient.zendesk.messaging.createCampaign({
  name: 'Abandoned Cart Reminder',
  audience: {
    filters: [
      {
        type: 'custom_attribute',
        attribute: 'has_abandoned_cart',
        operator: 'equals',
        value: true
      },
      {
        type: 'last_seen',
        operator: 'within',
        value: '24_hours'
      }
    ]
  },
  message: {
    type: 'structured',
    content: {
      text: 'You left some items in your cart!',
      buttons: [
        {
          text: 'Complete Purchase',
          url: 'https://example.com/cart',
          type: 'web_url'
        },
        {
          text: 'Need Help?',
          payload: 'CART_HELP',
          type: 'postback'
        }
      ]
    }
  },
  schedule: {
    type: 'immediate'
  }
});

// Handle incoming webhook
app.post('/webhook/zendesk', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'message.received') {
    const { conversation_id, message } = event.data;
    
    // Process user message
    if (message.text.toLowerCase().includes('urgent')) {
      // Escalate to agent
      await mcpClient.zendesk.messaging.transferConversation({
        conversationId: conversation_id,
        targetType: 'group',
        targetId: urgentTeamId,
        message: 'Escalating urgent request to specialized team'
      });
    }
  }
  
  res.sendStatus(200);
});

// Get conversation history
const history = await mcpClient.zendesk.messaging.getConversation({
  conversationId: 'conv_123',
  include: ['messages', 'participants', 'metadata']
});

// Update conversation metadata
await mcpClient.zendesk.messaging.updateConversation({
  conversationId: 'conv_123',
  metadata: {
    priority: 'high',
    category: 'sales',
    sentiment: 'positive',
    custom_fields: {
      account_value: 'premium',
      region: 'north_america'
    }
  },
  tags: ['vip', 'sales-lead']
});

// Configure web widget
const widgetConfig = await mcpClient.zendesk.messaging.updateWidget({
  settings: {
    color: {
      theme: '#1976d2',
      message: '#333333',
      action: '#2196f3'
    },
    position: {
      horizontal: 'right',
      vertical: 'bottom'
    },
    launcher: {
      chatLabel: 'Chat with us',
      minimizedLabel: 'Questions?'
    },
    prechatForm: {
      greeting: 'Hi! Let us know how we can help.',
      fields: [
        {
          type: 'name',
          required: true
        },
        {
          type: 'email',
          required: true
        },
        {
          type: 'department',
          options: ['Sales', 'Support', 'Billing']
        }
      ]
    },
    businessHours: {
      enabled: true,
      timezone: 'America/New_York',
      schedule: [
        { day: 'mon', start: '09:00', end: '17:00' },
        { day: 'tue', start: '09:00', end: '17:00' },
        { day: 'wed', start: '09:00', end: '17:00' },
        { day: 'thu', start: '09:00', end: '17:00' },
        { day: 'fri', start: '09:00', end: '17:00' }
      ],
      offlineMessage: "We're currently offline. Leave a message and we'll get back to you!"
    }
  }
});

Common Use Cases

Customer Support

• Live chat assistance
• Automated responses
• Multi-channel support
• Context preservation

Sales Engagement

• Lead qualification
• Product recommendations
• Demo scheduling
• Quote generation

Bot Automation

• FAQ handling
• Order tracking
• Appointment booking
• Form collection

Proactive Outreach

• Cart abandonment
• Customer onboarding
• Feature announcements
• Feedback collection

Security Best Practices

1. Authentication:

   • Use secure OAuth flow
   • Rotate credentials
   • Implement token refresh
   • Monitor access logs

2. Data Protection:

   • Encrypt sensitive data
   • Mask personal information
   • Implement data retention
   • Audit message access

3. Bot Security:

   • Validate user input
   • Sanitize responses
   • Implement rate limiting
   • Monitor bot behavior

Troubleshooting

Common Issues

1. Connection Errors

   • Verify webhook URLs
   • Check WebSocket connection
   • Validate SSL certificates
   • Review firewall rules

2. Message Delivery

   • Check channel status
   • Verify participant state
   • Review message format
   • Monitor rate limits

3. Bot Issues

   • Test intent detection
   • Validate flow logic
   • Check webhook responses
   • Review error handling

Getting Help

• Documentation: AI Gateway Docs
• Support: support@cequence.ai
• Zendesk API: developer.zendesk.com/api-reference/live-chat

---