RingCentral Agent Availability Integration

The RingCentral integration enables CallGrid to receive real-time agent availability updates from your RingCentral call queue environment. This integration uses RingCentral's REST API to monitor call queue presence and route calls intelligently based on current agent availability and queue capacity.

Prerequisites

Before setting up this integration, ensure you have:

• An active RingCentral account with administrative privileges
• Access to your RingCentral Admin Portal
• A generated OAuth2 Bearer Authentication Token from your RingCentral account
• Your specific Call Queue Group ID and Account ID

Configuration Steps

Step 1: Generate OAuth2 Bearer Authentication Token

1. Log into your RingCentral Developer Console
2. Create or access your RingCentral application
3. Generate OAuth2 credentials with appropriate permissions:
4. • ReadCallQueues permission for call queue access
   • ReadPresence permission for agent presence data
4. Use the OAuth2 flow to obtain a Bearer token
5. Copy the token securely (you'll need this for the integration)

Step 2: Identify Your Account ID and Call Queue Group ID

Account ID:

1. In your RingCentral Admin Portal, note your account identifier
2. Use ~ for the current account (recommended) or specify your numeric account ID
3. Example: ~ (current account) or 123456789

Call Queue Group ID:

1. Navigate to Groups & Users → Call Queues in your RingCentral Admin Portal
2. Select the call queue you want to monitor for agent availability
3. Note the Call Queue Group ID from the queue details
4. This ID identifies which queue to monitor for agent presence

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

Required Configuration Fields

Call Queue Group ID (Required)

• Enter your RingCentral call queue group ID
• This identifies which call queue to monitor for agent availability
• Example: 987654321

Account ID (Required)

• Enter your RingCentral account ID
• Use ~ for the current account or specify your numeric account ID
• Example: ~ (recommended) or 123456789

Bearer Authentication Token (Required)

• Paste your RingCentral OAuth2 Bearer authentication token
• This token authenticates your requests to RingCentral's REST API
• Example: Bearer abc123def456ghi789jkl012mno345

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

https://platform.ringcentral.com/restapi/v1.0/account/AccountID/call-queues/GroupID/presence

HTTP Method

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

Authentication Headers

The system automatically configures the Authorization header:

• Key: Authorization
• Value: Bearer Token (your OAuth2 Bearer token)

Acceptance Parsing

The integration supports advanced Regex pattern matching for call queue presence data.

Parsing Type

• Parse Type: Regex (automatically configured for optimal performance)
• Regex Type: Count
• Pattern: "acceptCurrentQueueCalls": true

Default Acceptance Criteria The system is pre-configured to count agents accepting current queue calls:

• Regex Type: Count
• Pattern: "acceptCurrentQueueCalls": true
• Condition: Configure based on your requirements
• Value: Set minimum number of available agents

This configuration counts agents who are currently accepting calls for the specified queue.

Agent Availability Parsing

Response Field Options Configure which fields from the RingCentral API response to use for agent availability:

• Property Path: Enter the JSON path to the availability data
• Common Fields:
• • Agent presence objects with queue acceptance status
  • Individual agent availability indicators
  • Queue-specific presence information
  • Real-time call acceptance status

Testing Your Configuration

To test your integration:

1. Fill in your Call Queue Group ID, Account ID, and Bearer Authentication Token
2. Click Run Webhook button to test the connection
3. Verify the test passes and shows your current call queue presence data
4. Confirm the acceptance parsing works correctly with your criteria

The webhook test will connect to your RingCentral system in real-time and show you whether calls would be accepted based on your current queue presence settings.

How It Works

Call Queue Presence Monitoring

The integration monitors real-time call queue presence through RingCentral's Presence API:

1. Real-time Polling: CallGrid checks call queue presence before routing each call
2. Queue-Specific Monitoring: The system monitors the specific call queue you've configured
3. Acceptance Status: Uses regex patterns to identify agents accepting queue calls
4. Smart Routing: Calls are only sent when agent availability meets your thresholds

API Response Structure

RingCentral's Call Queue Presence API returns availability data in the following format:

{

  "records": [

    {

      "extension": {

        "id": "12345",

        "extensionNumber": "101"

      },

      "acceptCurrentQueueCalls": true,

      "presenceStatus": "Available"

    },

    {

      "extension": {

        "id": "12346",

        "extensionNumber": "102"

      },

      "acceptCurrentQueueCalls": false,

      "presenceStatus": "Busy"

    }

  ],

  "paging": {

    "page": 1,

    "totalPages": 1,

    "totalElements": 2

  }

}

Advanced Configuration Examples

Example 1: Basic Queue Call Acceptance

Acceptance Criteria (Regex):

• Regex Type: Count
• Pattern: "acceptCurrentQueueCalls": true
• Condition: Greater Than
• Value: 0

This configuration accepts calls only when at least one agent is accepting current queue calls.

Example 2: Multiple Agent Threshold

Acceptance Criteria (Regex):

• Regex Type: Count
• Pattern: "acceptCurrentQueueCalls": true
• Condition: Greater Than
• Value: 1

This setup ensures calls are accepted only when at least 2 agents are accepting queue calls.

Example 3: Available Status with Queue Acceptance

Acceptance Criteria (Regex):

• Regex Type: Count
• Pattern: "acceptCurrentQueueCalls": true.*"presenceStatus": "Available"
• Condition: Greater Than
• Value: 0

This configuration checks for agents who are both accepting queue calls and have "Available" presence status.

Example 4: High-Volume Staffing Requirements

Acceptance Criteria (Regex):

• Regex Type: Count
• Pattern: "acceptCurrentQueueCalls": true
• Condition: Greater Than
• Value: 2

This configuration requires at least 3 agents accepting queue calls before routing calls.

Advanced Use Cases (Optional)

Multi-Queue Monitoring

Configure multiple CallGrid destinations, each monitoring different RingCentral call queues for specialized routing based on queue type or department.

Presence-Based Routing

Leverage RingCentral's presence system combined with queue acceptance status for intelligent call distribution.

Extension-Specific Distribution

Use extension-based routing for calls that require specific agent skills or departments within your RingCentral environment.

OAuth2 Token Management

Token Generation

Generate Bearer tokens using RingCentral's OAuth2 flow:

curl -X POST "https://platform.ringcentral.com/restapi/oauth/token" \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Token Refresh

• OAuth2 tokens have expiration times
• Implement token refresh logic in your application
• Monitor token validity and refresh before expiration

Troubleshooting

Common Issues

Authentication Failures

• Verify your OAuth2 Bearer token is current and valid
• Ensure the token has proper permissions for call queue and presence access
• Check that your RingCentral account is active and accessible

Invalid Account ID or Call Queue Group ID

• Confirm your Account ID exists (use ~ for current account)
• Verify the Call Queue Group ID matches your RingCentral call queue
• Check that the call queue is active and properly configured

No Presence Data Returned

• Ensure agents are logged into your RingCentral system
• Verify agents are assigned to the specified call queue
• Check that call queue presence monitoring is enabled

Regex Pattern Matching Issues

• Test your regex patterns with sample response data
• Verify the pattern correctly matches the expected JSON structure
• Check for case sensitivity in field values

Testing the Integration

Manual API Test:

curl -H "Authorization: Bearer your_bearer_token_here" \

"https://platform.ringcentral.com/restapi/v1.0/account/~/call-queues/your_queue_id/presence"

Template Configuration Test:

1. After entering all required fields, click Save Webhook
2. Review the auto-generated URL and authentication headers

Advanced Configuration Test:

1. In the advanced configuration screen, click Run Webhook
2. Verify the API response contains expected call queue presence data
3. Test different regex patterns and acceptance criteria

Live Integration Test:

1. Monitor CallGrid logs for successful API calls
2. Verify call queue presence data is being parsed correctly
3. Test call routing based on queue acceptance conditions

Rate Limits and Considerations

• API Rate Limit: Monitor usage to stay within RingCentral's rate limits
• Response Time: Typically under 500ms for presence checks
• Data Freshness: Real-time call queue presence updates
• Token Management: Implement proper OAuth2 token refresh procedures

Support and Additional Resources

RingCentral Documentation

• RingCentral Developer Portal
• REST API Reference
• Call Queue Presence API
• OAuth2 Authentication Guide

CallGrid Support

If you need assistance with this integration:

1. Check the CallGrid logs for error messages
2. Verify all configuration parameters
3. Test API connectivity using provided curl commands
4. Contact CallGrid support with integration details