Skip to main content

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.

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.

Available MCP Tools​

The Zendesk Messaging MCP server provides the following tools:

Conversation Management​

  • listConversations - List conversations for a user with filtering and pagination
  • createConversation - Create a new conversation with participants

Message Operations​

  • listMessages - Retrieve messages from a conversation with pagination
  • sendMessage - Send text, image, file, or carousel messages

User Management​

  • createUser - Create new users in the messaging system

Switchboard & Routing​

  • listSwitchboards - View switchboard configurations for conversation routing
  • passControl - Transfer conversation control between integrations (e.g., bot to human agent)

Integration Management​

  • listIntegrations - List available integrations (web, iOS, Android, etc.)

Prerequisites​

  • Access to Cequence AI Gateway
  • Zendesk Messaging account (Smooch.io)
  • Admin permissions
  • API credentials (JWT token or API Key)

Step 1: Get API Credentials​

1.1 Access Zendesk Messaging Dashboard​

  1. Log in to your Zendesk Messaging account (Smooch.io)
  2. Navigate to Settings > API Keys
  3. Or go to your app dashboard at https://app.smooch.io

1.2 Generate API Credentials​

You can use either authentication method:

Option A: JWT Token

  1. Generate a JWT token with your app credentials
  2. Include the token in the Authorization header as: Bearer {token}

Option B: API Key (Basic Auth)

  1. Go to Settings > API Keys
  2. Create a new API Key or use existing credentials
  3. Format: {keyId}:{secret}
  4. Encode in Base64 for Basic authentication

1.3 Save Credentials​

  1. Copy your App ID (required for all API calls)
  2. Save your JWT token or API Key credentials (Key ID and Secret)
  3. Keep credentials secure and never commit to version control

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://api.smooch.io/v2
  2. Select endpoints:
    • Conversations: List and create conversations
    • Messages: List and send messages
    • Users: Create and manage users
    • Switchboards: Manage conversation routing
    • Integrations: List available integrations
  3. 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: Choose one of the following:

    Option A: JWT Bearer Token

    • Type: Bearer Token
    • Header: Authorization: Bearer {jwt_token}
    • Enter your JWT token

    Option B: API Key (Basic Auth)

    • Type: Basic Authentication
    • Header: Authorization: Basic {base64_encoded_keyId:secret}
    • Enter your Key ID and Secret
    • Format: {keyId}:{secret} encoded in Base64

  2. App ID: Required for all API calls

    • Include appId in the URL path for all endpoints
    • Example: /apps/{appId}/conversations

  3. Click Next

Authentication Details​

JWT Token Format:

  • Generate JWT with your app credentials
  • Include in Authorization header as Bearer token
  • Token must be valid and not expired

API Key Format:

  • Use Basic authentication scheme
  • Encode {keyId}:{secret} in Base64
  • Include in Authorization header

Step 8-10: Complete Setup​

Configure security, choose deployment, and deploy.

Using Your Zendesk Messaging MCP Server​

Setup Instructions:

Natural Language Commands​

Once your MCP server is set up, you can use natural language commands like:

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​