# Convoso Agent Availability Integration

> The Convoso integration enables CallGrid to receive real-time agent availability updates from your Convoso contact center environment.

Source: https://callgrid.com/knowledge-base/convoso-agent-availability-integration
Last updated: 2025-09-23
Topics: Integrations, Agent Availability

The Convoso integration enables CallGrid to receive real-time agent availability updates from your Convoso contact center environment. This integration uses Convoso's Agent Monitor API to check agent availability and route calls intelligently based on current staffing levels.

![](https://callgrid.com/api/media/file/ConvosoInt.png)

## Prerequisites

Before setting up this integration, ensure you have:

- An active Convoso account with administrative privileges
- Access to your Convoso Admin Panel
- A generated authentication token from your Convoso API settings
- Your specific Queue ID and Campaign ID for monitoring

## Configuration Steps

### Step 1: Generate Authentication Token

1. Log into your Convoso Admin Panel
2. Navigate to **API** settings
3. Generate or locate your **Authentication Token**
4. Copy the token securely (you'll need this for the integration)

### Step 2: Identify Your Queue and Campaign IDs

1. In your Convoso Admin Panel, note your **Queue ID** for the queue you want to monitor
2. Identify your **Campaign ID** for the specific campaign you're tracking
3. These numeric identifiers will be used in the integration setup

### 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 **Convoso** from the Agent Availability templates
6. Fill in the required fields:

##### Required Configuration Fields

**Queue ID** _(Required)_

- Enter your Convoso queue identifier (numeric value)
- This identifies which queue to monitor for agent availability
- Example: 12345

**Auth Token** _(Required)_

- Paste your Convoso authentication token
- This token authenticates your API requests to Convoso
- Example: abc123def456ghi789

**Campaign ID** _(Required)_

- Enter your Convoso campaign identifier (numeric value)
- This specifies which campaign to monitor for agent activity
- Example: 67890

1. 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.

![](https://callgrid.com/api/media/file/ConvosoAdvanced.png)

##### Acceptance Parsing

The most important setting is the acceptance criteria, which determines when calls should be sent to this destination.

**Minimum Agent Threshold** The system is pre-configured to check for available agents using the data.available_agents field. You can adjust the minimum number of agents required:

- **Value: 0** - Accept calls when any agents are available (default)
- **Value: 1** - Accept calls when at least 2 agents are available
- **Value: 2** - Accept calls when at least 3 agents are available
- **Value: 3** - Accept calls when at least 4 agents are available

Simply change the number in the "Value" field to set your minimum agent requirement.

##### Testing Your Configuration

To test your integration:

1. Fill in your **Queue ID**, **Auth Token**, and **Campaign ID** in the configuration boxes
2. Click **Run Webhook**
3. Verify the test passes and shows agent availability data from your Convoso system
4. Confirm the acceptance parsing criteria work correctly

The test will show you real data from your Convoso Agent Monitor and whether calls would be accepted based on your settings.

## Advanced Configuration Examples

### Example 1: Basic Available Agent Check

**Acceptance Criteria:**

- Field: data.available_agents
- Condition: Greater Than
- Value: 0

This configuration accepts calls only when at least one agent is available in the monitored queue.

### Example 2: Multiple Agent Threshold

**Acceptance Criteria:**

- Field: data.available_agents
- Condition: Greater Than
- Value: 2

This setup ensures calls are accepted only when at least 3 agents are available and ready.

### Example 3: High-Volume Staffing Requirements

**Acceptance Criteria:**

- Field: data.available_agents
- Condition: Greater Than
- Value: 4

This configuration requires at least 5 available agents before accepting calls, ensuring adequate staffing for busy periods.

## Troubleshooting

### Common Issues

**Authentication Failures**

- Verify your Auth Token is correct and current
- Ensure the token has proper permissions for API access
- Check that your Convoso account is active and accessible

**Invalid Queue or Campaign ID**

- Confirm your Queue ID exists in your Convoso system
- Verify the Campaign ID is active and running
- Check that IDs are numeric values without extra characters

**No Agent Data Returned**

- Ensure agents are logged into the specified queue
- Verify the campaign is active and agents are assigned
- Check that the Agent Monitor is functioning properly

### Testing the Integration

To test your Convoso integration:

1. Enter your **Queue ID**, **Auth Token**, and **Campaign ID** in the configuration fields
2. Click **Run Webhook** button to test the connection
3. Verify the test passes and shows your current agent availability data
4. Confirm the acceptance parsing works correctly with your agent threshold

The webhook test will connect to your Convoso Agent Monitor in real-time and show you whether calls would be accepted based on your current agent availability and threshold settings.

### Rate Limits and Considerations

- Monitor API usage to stay within Convoso's rate limits
- Agent availability data updates based on Convoso's refresh intervals
- Consider the performance impact of frequent API calls during peak hours

## Support and Additional Resources

### Convoso Documentation

- [Convoso API Documentation](https://help.convoso.com/hc/en-us/articles/360043003034-How-to-get-Agent-Productivity-through-API)
- [Partner Integration Guide](https://www.convoso.com/advanced-features/partner-integration/)

### CallGrid Support

If you need assistance with this integration:

1. Check the CallGrid logs for error messages
2. Verify all configuration parameters
3. Contact CallGrid support with integration details