Zendesk Widgets MCP Server

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

About Zendesk Widgets API

Zendesk Widgets provide embeddable customer service components for websites and applications. The API enables customization of help widgets, contact forms, chat interfaces, and knowledge base search, creating seamless customer support experiences.

Key Capabilities

• Web Widget: Embeddable support interface
• Help Center Widget: Knowledge base search
• Contact Forms: Ticket creation forms
• Chat Widget: Live messaging interface
• Feedback Widget: Satisfaction surveys
• Custom Branding: Theme customization
• Mobile Support: Responsive design
• Multi-language: Localized interfaces

API Features

• Widget Configuration: Settings management
• Theme Customization: Visual styling
• OAuth 2.0: Secure authentication
• Embed Code: Integration snippets
• Analytics: Usage metrics
• Custom Fields: Extended forms
• Conditional Logic: Smart routing
• Mobile SDK: App integration

What You Can Do with Zendesk Widgets MCP Server

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

Web Widget Configuration

• Widget Setup

  • "Enable web widget on site"
  • "Configure widget position"
  • "Set widget colors"
  • "Add company branding"

• Feature Control

  • "Enable chat function"
  • "Add contact form"
  • "Include help center search"
  • "Configure ticket form"

• Behavior Settings

  • "Set widget visibility"
  • "Configure auto-popup"
  • "Set business hours"
  • "Enable offline form"

Theme Customization

• Visual Design

  • "Change widget theme color"
  • "Upload custom logo"
  • "Set brand colors"
  • "Configure font styles"

• Layout Options

  • "Position widget bottom-right"
  • "Create floating button"
  • "Design compact mode"
  • "Enable full-screen view"

• Mobile Styling

  • "Optimize for mobile"
  • "Set mobile breakpoints"
  • "Configure touch targets"
  • "Design responsive layout"

Contact Forms

• Form Builder

  • "Create support form"
  • "Add custom fields"
  • "Set required fields"
  • "Configure dropdowns"

• Field Types

  • "Add text input"
  • "Create dropdown menu"
  • "Insert file upload"
  • "Add checkbox group"

• Form Logic

  • "Set conditional fields"
  • "Configure field validation"
  • "Add field dependencies"
  • "Create multi-step forms"

Help Center Integration

• Search Widget

  • "Enable article search"
  • "Configure search scope"
  • "Set search filters"
  • "Customize results display"

• Content Display

  • "Show popular articles"
  • "Display recent updates"
  • "Filter by category"
  • "Enable article rating"

• Search Enhancement

  • "Add search suggestions"
  • "Configure auto-complete"
  • "Set search synonyms"
  • "Enable typo tolerance"

Chat Widget

• Chat Configuration

  • "Enable live chat"
  • "Set agent availability"
  • "Configure chat routing"
  • "Add pre-chat form"

• Chat Features

  • "Enable file sharing"
  • "Add emoji support"
  • "Configure typing indicators"
  • "Set message history"

• Chat Automation

  • "Add welcome message"
  • "Configure auto-responses"
  • "Set up chat bots"
  • "Create canned responses"

Analytics & Insights

• Usage Metrics

  • "Track widget interactions"
  • "Monitor form submissions"
  • "Measure chat engagement"
  • "Analyze search queries"

• Performance Data

  • "Show widget load times"
  • "Track completion rates"
  • "Monitor error rates"
  • "Measure user satisfaction"

• User Behavior

  • "Analyze navigation paths"
  • "Track popular articles"
  • "Monitor chat patterns"
  • "Study form abandonment"

Multi-language Support

• Localization

  • "Enable multiple languages"
  • "Configure language detection"
  • "Set default language"
  • "Add custom translations"

• Content Adaptation

  • "Translate form labels"
  • "Localize error messages"
  • "Adapt date formats"
  • "Configure RTL support"

• Regional Settings

  • "Set timezone display"
  • "Configure currency"
  • "Adapt cultural elements"
  • "Set regional defaults"

Integration Options

• Website Embedding

  • "Generate embed code"
  • "Create script tags"
  • "Configure async loading"
  • "Set up CSP policies"

• CMS Integration

  • "WordPress plugin setup"
  • "Shopify integration"
  • "Drupal module config"
  • "Custom CMS embedding"

• Mobile Apps

  • "iOS SDK integration"
  • "Android SDK setup"
  • "React Native config"
  • "Flutter integration"

Advanced Configuration

• Security Settings

  • "Configure CORS policy"
  • "Set domain restrictions"
  • "Enable SSL only"
  • "Configure CSP headers"

• Performance Optimization

  • "Enable lazy loading"
  • "Configure caching"
  • "Optimize asset delivery"
  • "Set up CDN"

• Custom Integration

  • "Add custom CSS"
  • "Include custom JavaScript"
  • "Set up webhooks"
  • "Configure API callbacks"

Prerequisites

• Access to Cequence AI Gateway
• Zendesk account with widget access
• Website or application to embed
• OAuth application credentials

Step 1: Create Zendesk OAuth Application

1.1 Access Admin Center

1. Log in to Zendesk
2. Go to Admin Center > Channels > Web Widget
3. Navigate to APIs section
4. Click OAuth Clients tab

1.2 Create OAuth Client

1. Click Add OAuth Client
2. Fill in details:
   • Client Name: "AI Gateway Widgets MCP"
   • Company: Your company name
   • Description: "Widget configuration and management"
   • Redirect URLs:

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

1.3 Configure Permissions

1. Set client type to Confidential
2. Select widget scopes:
   • read - View widget settings
   • write - Modify widget configuration

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 Widgets API, and create MCP server.

Step 5: Configure API Endpoints

1. Base URL: https://{subdomain}.zendesk.com/api/v2
2. Select endpoints:
   • Widget settings endpoints
   • Theme endpoints
   • Analytics endpoints
3. Click Next

Step 6: MCP Server Configuration

1. Name: "Zendesk Widgets"
2. Description: "Web widgets and customer portal"
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 Widgets OAuth Scopes

Widget Scopes

• read

  • View widget settings
  • Access theme configuration
  • Read analytics data
  • See form configurations

• write

  • Update widget settings
  • Modify themes
  • Configure forms
  • Manage integrations

Recommended Scope Combinations

For Widget Management:

read
write

Step 8-10: Complete Setup

Configure security, choose deployment, and deploy.

Using Your Zendesk Widgets MCP Server

With Claude Desktop

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

Natural Language Commands

• "Enable web widget with company branding"
• "Configure contact form with custom fields"
• "Set widget to appear on all pages"
• "Add live chat to customer portal"
• "Customize widget colors to match brand"

API Integration Example

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

// Configure web widget
const widgetConfig = await mcpClient.zendesk.widgets.updateWebWidget({
  web_widget: {
    enabled: true,
    classic: false,
    position: 'bottom-right',
    offset: {
      horizontal: '20px',
      vertical: '20px'
    },
    color: {
      theme: '#1976d2',
      launcher: '#2196f3',
      launcherText: '#ffffff',
      button: '#1976d2',
      resultLists: '#ffffff',
      header: '#1976d2',
      articleLinks: '#1976d2'
    },
    zIndex: 999999,
    mobile: {
      position: 'bottom-right',
      labelVisible: true
    }
  }
});

// Configure contact form
const contactForm = await mcpClient.zendesk.widgets.updateContactForm({
  contact_form: {
    enabled: true,
    title: 'Contact Support',
    subject_field: {
      enabled: true,
      required: true
    },
    email_field: {
      enabled: true,
      required: true
    },
    description_field: {
      enabled: true,
      required: true,
      placeholder: 'Please describe your issue in detail...'
    },
    ticket_field_ids: [customFieldId1, customFieldId2],
    custom_fields: [
      {
        id: customFieldId1,
        label: 'Product Category',
        type: 'dropdown',
        required: true,
        options: [
          { value: 'software', label: 'Software' },
          { value: 'hardware', label: 'Hardware' },
          { value: 'service', label: 'Service' }
        ]
      },
      {
        id: customFieldId2,
        label: 'Priority Level',
        type: 'radio',
        required: false,
        options: [
          { value: 'low', label: 'Low' },
          { value: 'medium', label: 'Medium' },
          { value: 'high', label: 'High' },
          { value: 'urgent', label: 'Urgent' }
        ]
      }
    ],
    attachments: {
      enabled: true,
      max_size: '10MB',
      allowed_types: ['image/*', '.pdf', '.doc', '.docx']
    }
  }
});

// Configure help center widget
const helpCenterWidget = await mcpClient.zendesk.widgets.updateHelpCenter({
  help_center: {
    enabled: true,
    filter: {
      section_ids: [sectionId1, sectionId2],
      category_ids: [categoryId1],
      label_names: ['customer-facing']
    },
    search: {
      enabled: true,
      placeholder: 'Search for help...',
      suggestions: {
        enabled: true,
        articles: [
          { id: articleId1, title: 'Getting Started Guide' },
          { id: articleId2, title: 'Account Setup' },
          { id: articleId3, title: 'Billing FAQ' }
        ]
      }
    },
    contextual_help: {
      enabled: true,
      values: [
        {
          url: '/checkout',
          articles: [checkoutArticleId1, checkoutArticleId2]
        },
        {
          url: '/account',
          articles: [accountArticleId1, accountArticleId2]
        }
      ]
    }
  }
});

// Configure chat widget
const chatWidget = await mcpClient.zendesk.widgets.updateChat({
  chat: {
    enabled: true,
    departments: {
      enabled: true,
      select: 'sales,support,billing'
    },
    prechat_form: {
      greeting_message: 'Welcome! How can we help you today?',
      name_field: {
        enabled: true,
        required: true
      },
      email_field: {
        enabled: true,
        required: true
      },
      phone_field: {
        enabled: false
      },
      department_field: {
        enabled: true,
        required: false
      },
      message_field: {
        enabled: true,
        required: false,
        placeholder: 'How can we help?'
      }
    },
    offline_form: {
      greeting_message: 'We\'re currently offline. Leave us a message!',
      name_field: { enabled: true, required: true },
      email_field: { enabled: true, required: true },
      message_field: { enabled: true, required: true }
    },
    concierge: {
      enabled: true,
      name: 'Support Bot',
      avatar_path: 'https://example.com/bot-avatar.png',
      greeting_message: 'Hi! I\'m here to help. What can I do for you?'
    }
  }
});

// Configure authentication
const authentication = await mcpClient.zendesk.widgets.updateAuthentication({
  authentication: {
    jwt_secret: jwtSecret,
    shared_secret: sharedSecret,
    external_id_field: 'user_id',
    name_field: 'name',
    email_field: 'email',
    organization_field: 'organization',
    tags_field: 'tags',
    remote_photo_url_field: 'avatar_url'
  }
});

// Get widget analytics
const analytics = await mcpClient.zendesk.widgets.getAnalytics({
  start_date: '2025-01-01',
  end_date: '2025-01-31',
  metrics: [
    'widget_views',
    'form_submissions',
    'chat_conversations',
    'help_center_searches',
    'article_views',
    'conversion_rate'
  ],
  group_by: 'day'
});

// Generate embed code
const embedCode = await mcpClient.zendesk.widgets.generateEmbedCode({
  subdomain: 'your-subdomain',
  settings: {
    webWidget: {
      launcher: {
        chatLabel: {
          '*': 'Chat with us'
        },
        label: {
          '*': 'Support'
        }
      },
      contactForm: {
        attachments: true,
        subject: true
      },
      helpCenter: {
        originalArticleButton: true,
        filter: {
          section: sectionId1,
          category: categoryId1
        }
      },
      talk: {
        enabled: false
      },
      answerBot: {
        enabled: true,
        avatar: {
          url: 'https://example.com/bot-avatar.png',
          name: 'Support Bot'
        }
      }
    }
  }
});

// Create custom CSS
const customCSS = `
  .zEWidget-launcher {
    border-radius: 50px !important;
    box-shadow: 0 4px 12px rgba(0,0,0,0.15) !important;
  }
  
  .zEWidget-launcher:hover {
    transform: scale(1.05);
    transition: transform 0.2s ease;
  }
  
  .zEWidget-webWidget {
    font-family: 'Helvetica Neue', sans-serif !important;
  }
  
  .zEWidget-webWidget-header {
    background: linear-gradient(45deg, #1976d2, #2196f3) !important;
  }
`;

await mcpClient.zendesk.widgets.updateCustomCSS({
  css: customCSS
});

// Configure business hours
await mcpClient.zendesk.widgets.updateBusinessHours({
  business_hours: {
    enabled: true,
    timezone: 'America/New_York',
    schedule: {
      monday: { enabled: true, start: '09:00', end: '17:00' },
      tuesday: { enabled: true, start: '09:00', end: '17:00' },
      wednesday: { enabled: true, start: '09:00', end: '17:00' },
      thursday: { enabled: true, start: '09:00', end: '17:00' },
      friday: { enabled: true, start: '09:00', end: '17:00' },
      saturday: { enabled: false },
      sunday: { enabled: false }
    },
    offline_message: 'We\'re currently offline. Please leave a message and we\'ll get back to you!'
  }
});

Common Use Cases

Customer Support Portal

• Help desk widget
• Knowledge base search
• Contact forms
• Live chat support

E-commerce Support

• Product help
• Order assistance
• Return requests
• Customer service

SaaS Applications

• In-app support
• Feature help
• User onboarding
• Feedback collection

Website Integration

• Support widget
• Contact forms
• FAQ search
• Customer portal

Security Best Practices

1. Widget Security:

   • Use HTTPS only
   • Configure CSP headers
   • Set domain restrictions
   • Validate embed origins

2. Data Protection:

   • Encrypt form data
   • Secure authentication
   • Audit form submissions
   • Implement rate limiting

3. Access Control:

   • Role-based permissions
   • Widget visibility rules
   • Feature restrictions
   • User authentication

Troubleshooting

Common Issues

1. Widget Loading

   • Check script placement
   • Verify domain settings
   • Test network connectivity
   • Review console errors

2. Styling Issues

   • Validate CSS conflicts
   • Check z-index values
   • Test responsive design
   • Review browser compatibility

3. Form Submission

   • Verify required fields
   • Check validation rules
   • Test file uploads
   • Review error handling

Getting Help

• Documentation: AI Gateway Docs
• Support: support@cequence.ai
• Zendesk Widgets: support.zendesk.com/hc/en-us/articles/203908456

---