Zendesk Agent Availability Integration

The Zendesk Agent Availability integration enables CallGrid to check real-time agent status before routing calls to your Zendesk Support environment. This integration uses Zendesk's Agent Availability API to monitor agent availability across different channels and ensures calls are only sent when agents are online and ready to handle them.

Prerequisites

Before setting up this integration, ensure you have:

• An active Zendesk Support account with Omnichannel Contact Center enabled
• Administrative access to your Zendesk account
• API authentication credentials (email and API token)
• Your Zendesk subdomain information

Configuration Steps

Step 1: Generate Zendesk API Credentials

1. Log into your Zendesk Admin Center
2. Navigate to Apps and integrations → APIs → Zendesk API
3. Enable API access if not already enabled
4. Generate an API token:
5. • Click Add API token
   • Enter a description for the token
   • Copy the generated token securely
5. Note your email address (used for authentication)

Step 2: Prepare Authentication

Create a Base64 encoded authentication string using the format: email/token:api_token

For example, if your email is admin@company.com and your API token is abc123, you would encode: admin@company.com/token:abc123

Step 3: Configure CallGrid Integration

Phase 1: Basic Template Setup

1. Navigate to your CallGrid destination settings
2. Click the Webhook tab
3. Enable Webhook Integration
4. Enable Template Mode
5. Select Agent Availability template type
6. Select Zendesk from the available templates
7. Fill in the required fields:

Required Configuration Fields

Subdomain (Required)

• Enter your Zendesk subdomain
• Example: yourcompany (if your Zendesk URL is yourcompany.zendesk.com)

Basic Auth Token (Required)

• Enter your Base64 encoded email:password for basic authentication
• Format: Base64 encoded string of email/token:api_token
• Example: YWRtaW5AY29tcGFueS5jb20vdG9rZW46YWJjMTIz

8. Click Save Webhook to proceed to advanced configuration

Phase 2: Advanced Configuration (Optional)

After saving your basic template configuration, you'll be taken to the advanced configuration screen. The system automatically builds the webhook URL and authentication headers for you.

Request Configuration

URL Structure The webhook URL is automatically generated based on your configuration:

HTTP Method

• Method: GET (automatically configured)
• Timeout: 10 seconds (default, adjustable)

Authentication Headers

The system automatically configures the required headers:

• Authorization: Basic TEMPLATE_BASIC_AUTH (your Base64 encoded credentials)
• Zendesk-Api-Version: 2023-02-01 (API version header)

Acceptance Parsing

The integration uses advanced Regex pattern matching to count online agents from the JSON response.

Parsing Configuration

• Parse Type: Regex (automatically configured)
• Regex Type: Count
• Pattern: "agent_status":{"name":"online"}

Default Acceptance Criteria The system counts agents with "online" status using regex pattern matching. The default configuration accepts calls when at least one agent is online.

Advanced Parsing Options

You can customize the regex pattern to match different agent status conditions:

Available Patterns:

• "agent_status":{"name":"online"} - Counts agents with online status
• "agent_status":{"name":"offline"} - Counts agents with offline status
• "agent_status":{"name":"away"} - Counts agents with away status

Testing Your Configuration

To test your integration:

1. Fill in your Subdomain and Basic Auth Token
2. Click Run Webhook to test the connection
3. Verify the test passes and shows current agent availability data
4. Confirm the acceptance parsing correctly counts online agents
5. Check that the regex pattern matches the expected agent status format

The built-in webhook test will connect to your Zendesk system in real-time and show you whether calls would be accepted based on your current agent availability.

How It Works

Agent Availability Check

The integration monitors real-time agent status through Zendesk's Agent Availability API:

1. Real-time Polling: CallGrid checks agent availability before routing each call
2. Status Pattern Matching: Uses regex to count agents with specific status values
3. Smart Routing: Calls are only sent when online agent count meets your thresholds
4. Multi-Channel Support: Monitors agent status across different Zendesk channels

Advanced Configuration Examples

Example 1: Basic Online Agent Count

Acceptance Criteria:

• Regex Pattern: "agent_status":{"name":"online"}
• Condition: Greater Than
• Value: 0

This configuration accepts calls when at least one agent is online.

Example 2: Multiple Online Agents Required

Acceptance Criteria:

• Regex Pattern: "agent_status":{"name":"online"}
• Condition: Greater Than
• Value: 2

This setup ensures calls are only accepted when at least 3 agents are online.

Example 3: Exclude Away Agents

Acceptance Criteria:

• Regex Pattern: "agent_status":{"name":"online"}
• Condition: Greater Than
• Value: 1

Combined with a second criteria:

• Regex Pattern: "agent_status":{"name":"away"}
• Condition: Less Than
• Value: 5

This ensures sufficient online agents while limiting away agents.

Agent Status Types

Standard Zendesk Agent Statuses

• online: Agent is available and can receive work
• offline: Agent is not available for work
• away: Agent is temporarily unavailable

Custom Unified Statuses

If your Zendesk account has custom unified statuses enabled, you can also monitor for:

• Custom status names (e.g., "In a meeting", "On break")
• Channel-specific statuses (messaging, support, talk)

Advanced Use Cases

Multi-Channel Monitoring

Monitor agent availability across different Zendesk channels by adjusting regex patterns to target specific channel statuses.

Group-Based Routing

Combine agent availability with group membership data for routing calls to specific agent groups.

Capacity-Based Decisions

Use the API response to monitor agent workload and capacity across different channels.

Troubleshooting

Common Issues

Authentication Failures

• Verify your Base64 encoded credentials are correct
• Ensure your API token is valid and has appropriate permissions
• Check that your email address is correct and has admin access

Invalid Subdomain

• Confirm your subdomain matches your Zendesk account
• Verify the subdomain is spelled correctly
• Check that your Zendesk instance is accessible

No Agent Data Returned

• Ensure Omnichannel Contact Center is enabled on your account
• Verify agents are logged into your Zendesk system
• Check that the Agent Availability API is accessible

Regex Pattern Issues

• Test regex patterns with sample response data
• Verify patterns match the exact JSON structure returned by Zendesk
• Check for case sensitivity in agent status names

Testing the Integration

Template Configuration Test:

1. After entering subdomain and auth token, click Save Webhook
2. Review the auto-generated URL and headers

Built-in Webhook Test:

1. In the advanced configuration screen, click Run Webhook
2. Verify the API response contains expected agent availability data
3. Test different regex patterns and acceptance criteria
4. Confirm agent status counting works correctly

Live Integration Test:

1. Monitor CallGrid logs for successful API calls
2. Verify agent status data is being parsed correctly
3. Test call routing based on agent availability conditions

API Rate Limits

• Rate Limit: 300 requests per minute
• Response Time: Typically under 500ms for availability checks
• Data Freshness: Real-time agent status updates
• Concurrent Requests: Monitor usage to avoid hitting limits

CallGrid Support

If you need assistance with this integration:

1. Check the CallGrid logs for error messages
2. Verify all configuration parameters
3. Test the integration using the built-in webhook test feature
4. Contact CallGrid support with integration details