Ringba Real Time Bidding Integration

The Ringba Real Time Bidding (RTB) integration enables you to send bid requests to Ringba's marketplace in real-time. This integration allows you to monetize your call traffic by submitting calls to Ringba buyers who can bid on them dynamically based on call characteristics, geographic data, and caller information.

Other Helpful Ringba Articles:

1. Posting Bids from Ringba to CallGrid using RTB
2. Posting Conversions to Ringba from CallGrid
3. Receiving Conversion Events from CallGrid in Ringba
4. Receiving Bids from Ringba in CallGrid
   

Prerequisites

Before setting up this integration, ensure you have:

• An active Ringba account with RTB permissions
• Your Ringba RTB identifier from your account
• Understanding of your call routing and monetization strategy
• Knowledge of your target geographic markets

Configuration Steps

Step 1: Obtain Ringba RTB Information

1. Log into your Ringba account
2. Navigate to your RTB or marketplace settings
3. Locate your RTB ID (your unique identifier for RTB campaigns)
4. Ensure your account has RTB access and appropriate permissions
5. Verify that your RTB campaigns are active and accepting bids

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 Ringba from the Real Time Bidding templates
7. Fill in the required field:

Required Configuration Fields

RTB ID (Required)

• Enter your Ringba RTB identifier
• This is your unique identifier for RTB campaigns in Ringba
• Example: rtb123456

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 your configuration:

https://rtb.ringba.com/v1/production/RTBID.json?CID=[[tag:CallerId]]&State=[[tag:VisitorStateCode|tag:InboundStateCode]]&ZipCode=[[tag:VisitorZipCode|tag:InboundZipCode]]&exposeCallerId=yes

HTTP Method

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

URL Parameters The integration automatically includes these query parameters with dynamic values:

• CID: Caller ID from [[tag:CallerId]]
• State: State code with fallback logic - uses VisitorStateCode if available, otherwise InboundStateCode
• ZipCode: Zip code with fallback logic - uses VisitorZipCode if available, otherwise InboundZipCode
• exposeCallerId: Set to "yes" to expose caller ID to buyers

Dynamic Parameter Logic

The integration uses intelligent fallback logic for geographic parameters:

• State Parameter: [[tag:VisitorStateCode|tag:InboundStateCode]] - Uses visitor state if available, falls back to inbound state
• ZipCode Parameter: [[tag:VisitorZipCode|tag:InboundZipCode]] - Uses visitor zip if available, falls back to inbound zip

This ensures the most accurate geographic targeting for your calls.

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 bid amounts using the bidAmount field:

• Field: bidAmount
• Condition: Greater Than
• Value: 0

This configuration accepts bids when Ringba responds with a bid amount greater than 0.

Bid Response Handling

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

• Property Path: Enter the JSON path to the bid data
• Common Fields:
• • bidAmount - The bid amount offered for the call
  • targetNumber - Phone number where the call should be routed
  • campaignId - ID of the campaign that won the bid
  • buyerId - ID of the buyer making the offer

Testing Your Configuration

To test your integration:

1. Fill in your RTB ID
2. In the webhook testing section, provide test values for geographic targeting:
3. • tag:CallerId: Enter a test phone number (e.g., 5551234567)
   • tag:VisitorStateCode|tag:InboundStateCode: Enter a test state code (e.g., CA)
   • tag:VisitorZipCode|tag:InboundZipCode: Enter a test zip code (e.g., 90210)
3. Click Run Webhook to test the connection
4. Verify the test passes and shows a proper bid response from Ringba
5. Confirm the acceptance parsing works correctly with the response

The built-in webhook test will send a test bid request to Ringba 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 Ringba's RTB API:

1. Bid Request: CallGrid sends call and geographic information to Ringba's RTB endpoint
2. Campaign Evaluation: Ringba evaluates the call against available campaigns and buyers
3. Bid Response: Ringba responds with the highest bid and routing information
4. Acceptance Decision: Your system evaluates the bid response against your criteria
5. Call Routing: If accepted, the call is routed to the winning buyer's target number

Bid Response Structure

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

{

  "bidAmount": 25.50,

  "targetNumber": "18005551234",

  "campaignId": "camp123456",

  "buyerId": "buyer789",

  "callerId": "5551234567",

  "state": "CA",

  "zipCode": "90210",

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

}

Advanced Configuration Examples

Example 1: Basic Bid Acceptance

Acceptance Criteria:

• Field: bidAmount
• Condition: Greater Than
• Value: 0

This configuration accepts calls when Ringba offers any bid amount.

Example 2: Minimum Bid Threshold

Acceptance Criteria:

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

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

Example 3: Campaign Validation

Acceptance Criteria:

• Field: campaignId
• Condition: Not Equals
• Value: null

This configuration ensures calls are only accepted when a valid campaign is matched.

Example 4: Multiple Acceptance Criteria

You can add multiple criteria to ensure both valid campaigns and minimum bids:

Criteria 1:

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

Criteria 2:

• Field: targetNumber
• Condition: Not Equals
• Value: null

Geographic Targeting

State and Zip Code Optimization

Ringba's RTB system uses geographic data for intelligent targeting:

• State-Level Targeting: Campaigns can target specific states for regional optimization
• Zip Code Precision: Fine-grained targeting based on caller's zip code location
• Fallback Logic: Automatic fallback ensures geographic data is always provided

Data Quality Best Practices

• Ensure accurate state code formatting (2-letter codes: CA, NY, FL, etc.)
• Use 5-digit zip codes for precise targeting
• Monitor geographic data quality to maximize bid responses

Advanced Use Cases

Multi-RTB Strategy

Configure multiple CallGrid destinations, each targeting different Ringba RTB campaigns to maximize coverage and competition.

Geographic Optimization

Leverage Ringba's geographic targeting to route calls to buyers optimized for specific regions and markets.

Performance-Based Routing

Use bid amount data to route calls to the highest-paying campaigns and optimize revenue.

Troubleshooting

Common Issues

Invalid RTB ID

• Verify your RTB ID is correct and matches your Ringba account
• Ensure your RTB campaigns are active and accepting bids
• Check that the RTB ID format is correct

No Bid Responses

• Ensure there are active campaigns in your Ringba RTB setup
• Verify campaign targeting criteria match your call characteristics
• Check that campaigns have available budget and capacity

Geographic Data Issues

• Verify state codes are in correct 2-letter format
• Ensure zip codes are valid 5-digit codes
• Check that geographic tags are being populated correctly

Low Bid Amounts

• Review call quality to ensure it meets buyer standards
• Check that geographic targeting aligns with high-value campaigns
• Verify that call characteristics match buyer preferences

Testing the Integration

Template Configuration Test:

1. After entering RTB ID, click Save Webhook
2. Review the auto-generated URL and parameters

Built-in Webhook Test:

1. In the advanced configuration screen, provide test values:
2. • tag:CallerId: Enter a test phone number (e.g., 5551234567)
   • tag:VisitorStateCode|tag:InboundStateCode: Enter a test state code (e.g., CA)
   • tag:VisitorZipCode|tag:InboundZipCode: Enter a test zip code (e.g., 90210)
2. Click Run Webhook to test the connection
3. Verify the bid response contains expected campaign 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 amount acceptance conditions

Best Practices

Campaign Optimization

• Monitor bid performance across different geographic markets
• Track campaign success rates and optimize targeting accordingly
• Ensure call quality standards meet buyer requirements

Revenue Maximization

• Set competitive but realistic bid thresholds
• Monitor market rates and adjust expectations accordingly
• Track performance metrics across different RTB campaigns

Geographic Strategy

• Test different geographic markets to identify high-value areas
• Monitor state and zip code performance for optimization opportunities
• Adjust geographic targeting based on campaign 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 the integration using the built-in webhook test feature
4. Contact CallGrid support with integration details