CallGrid Real Time Call Bidding Integration

The CallGrid Real Time Call Bidding (RTB) integration enables you to send bid requests to other CallGrid customers or partners in real-time. This integration allows you to monetize your call traffic by sending calls to buyers who can bid on them dynamically based on call characteristics and current market conditions.

Prerequisites

Before setting up this integration, ensure you have:

• An active CallGrid account with real-time bidding permissions
• The Grid ID of the CallGrid customer you want to send bids to
• Understanding of your call routing and monetization strategy
• Appropriate call volume and quality metrics

Configuration Steps

Step 1: Obtain Grid ID from Buyer

1. Contact the CallGrid customer you want to send bid requests to
2. Request their Grid ID for real-time bidding integration
3. Verify that they are set up to receive and process bid requests
4. Confirm the types of calls they are interested in purchasing

Step 2: 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. Switch to Real Time Bidding template type
6. Select CallGrid from the Real Time Bidding templates
7. Fill in the required field:

Required Configuration Fields

Grid ID (Required)

• Enter the Grid ID of the CallGrid customer you want to send bids to
• This identifies which CallGrid account will receive your bid requests
• Example: abc123-def456-ghi789

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 request structure for you.

Request Configuration

URL Structure The webhook URL is automatically generated based on the Grid ID:

https://bid.callgrid.com/api/bid/GridID

HTTP Method

• Method: POST (automatically configured)
• Content-Type: application/json (automatically configured)
• Timeout: 10 seconds (default, adjustable)

JSON Request Body

The integration automatically includes dynamic call parameters in the POST body:

{

  "CallerId": "[[tag:CallerId]]",

  "InboundStateCode": "[[tag:InboundStateCode]]"

}

These parameters provide essential call information to the receiving CallGrid customer for bid evaluation.

Acceptance Parsing

The most important setting is the acceptance criteria, which determines when bids are accepted.

Parsing Type

• Parse Type: JSON (automatically configured)
• Parse Field: Configure which field from the bid response to evaluate

Default Acceptance Criteria The system is pre-configured to check for successful bid responses using the code field:

• Field: code
• Condition: Equals
• Value: 1000

This configuration accepts bids when the receiving CallGrid customer responds with a successful bid code (1000).

Bid Response Handling

Response Field Options Configure which fields from the CallGrid bid response to use for acceptance:

• Property Path: Enter the JSON path to the bid data
• Common Fields:
• • code - Response code indicating bid status
  • bid_amount - The bid amount offered for the call
  • destination - Where the call should be routed if accepted
  • message - Additional information about the bid

Testing Your Configuration

To test your integration:

1. Fill in the Grid ID in the configuration box
2. Provide test values for tag:CallerId and tag:InboundStateCode
3. Click Run Webhook button to test the connection
4. Verify the test passes and shows a proper bid response
5. Confirm the acceptance parsing works correctly with the response

The webhook test will send a test bid request to the specified CallGrid customer and show you whether bids would be accepted based on their response.

How It Works

Real-Time Bid Process

The integration facilitates real-time bidding through CallGrid's RTB system:

1. Bid Request: CallGrid sends call information to the specified Grid ID
2. Bid Evaluation: The receiving customer evaluates the call and responds with a bid
3. Acceptance Decision: Your system evaluates the bid response against your criteria
4. Call Routing: If accepted, the call is routed to the winning bidder's destination

Bid Response Structure

CallGrid's RTB API returns bid responses in the following format:

{

  "code": 1000,

  "message": "Bid accepted",

  "bid_amount": 25.50,

  "destination": "12125551234",

  "caller_id": "15551234567",

  "state_code": "CA",

  "timestamp": "2025-09-23T15:30:00Z"

}

Response Codes

Common Response Codes

• 1000: Bid accepted - Call should be routed to the bidder
• 2000: Bid declined - Bidder does not want this call
• 3000: No capacity - Bidder cannot handle calls at this time
• 4000: Invalid request - Problem with the bid request format
• 5000: System error - Technical issue with the bidder's system

Advanced Configuration Examples

Example 1: Basic Bid Acceptance

Acceptance Criteria:

• Field: code
• Condition: Equals
• Value: 1000

This configuration accepts calls only when the bidder responds with a successful bid code.

Example 2: Minimum Bid Amount

Acceptance Criteria:

• Field: bid_amount
• Condition: Greater Than
• Value: 20.00

This setup ensures calls are only accepted when the bid amount exceeds $20.00.

Example 3: Multiple Acceptance Criteria

You can add multiple criteria to ensure both successful bids and minimum amounts:

Criteria 1:

• Field: code
• Condition: Equals
• Value: 1000

Criteria 2:

• Field: bid_amount
• Condition: Greater Than
• Value: 15.00

Example 4: Message-Based Filtering

Acceptance Criteria:

• Field: message
• Condition: Contains
• Value: accepted

This configuration accepts bids based on message content confirmation.

Advanced Use Cases

Multi-Buyer Strategy

Configure multiple CallGrid destinations, each targeting different Grid IDs to maximize bid competition and revenue.

Call Quality Optimization

Use bid responses to route high-quality calls to premium buyers who offer better rates.

Geographic Targeting

Leverage the automatic state code parameter to route calls to buyers specialized in specific geographic regions.

Troubleshooting

Common Issues

Invalid Grid ID

• Verify the Grid ID is correct and belongs to an active CallGrid customer
• Confirm the receiving customer has RTB enabled and configured
• Check that the Grid ID format matches CallGrid's requirements

No Bid Responses

• Ensure the receiving CallGrid customer is actively accepting bids
• Verify their system is properly configured to handle bid requests
• Check that your call types match their buying criteria

Bid Rejection Issues

• Review your acceptance criteria to ensure they're not too restrictive
• Check the bid response codes to understand why bids are being declined
• Verify that bid amounts meet your minimum requirements

Connection Timeouts

• Check network connectivity to CallGrid's bidding platform
• Verify the receiving customer's system is responding within timeout limits
• Consider adjusting timeout settings if needed

Testing the Integration

Template Configuration Test:

1. After entering Grid ID, click Save Webhook
2. Review the auto-generated URL and request structure

Built-in Webhook Test:

1. In the advanced configuration screen, provide test values for variables:
2. • tag:CallerId: Enter a test phone number (e.g., 5551234567)
   • tag:InboundStateCode: Enter a test state code (e.g., CA)
2. Click Run Webhook to test the connection
3. Verify the bid response contains expected data
4. Test different acceptance criteria using the webhook test feature

Live Integration Test:

1. Monitor CallGrid logs for successful bid requests
2. Verify bid responses are being parsed correctly
3. Test call routing based on bid acceptance conditions

Best Practices

Bid Request Optimization

• Include relevant call metadata to help buyers make informed decisions
• Ensure call quality metrics are accurate and up-to-date
• Provide consistent call volume to maintain buyer relationships

Response Handling

• Set appropriate timeout values for bid responses
• Implement fallback routing for declined bids
• Monitor bid acceptance rates and adjust criteria as needed

Revenue Optimization

• Test different minimum bid amounts to optimize revenue
• Track performance metrics for different buyers
• Adjust routing strategies based on buyer response patterns

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