Retreaver Real Time Bidding Integration

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

Prerequisites

Before setting up this integration, ensure you have:

• An active Retreaver account with RTB permissions
• Your Retreaver RTB authentication key
• Publisher ID from your Retreaver account
• Understanding of your call routing and monetization strategy

Configuration Steps

Step 1: Obtain Retreaver Account Information

1. Log into your Retreaver account
2. Navigate to your RTB or publisher settings
3. Locate your RTB Key (authentication key for RTB requests)
4. Find your Publisher ID (your unique identifier for the routing service)
5. Ensure your account has RTB access and appropriate permissions

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

Required Configuration Fields

RTB Key (Required)

• Enter your Retreaver RTB authentication key
• This key authenticates your requests to Retreaver's RTB system
• Example: abc123def456ghi789jkl012

Publisher ID (Required)

• Enter your Publisher ID from Retreaver
• This is your unique identifier for the routing service
• Example: pub123456

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.retreaver.com/rtbs.json?key=Key&publisher_id=ID&caller_number=[[tag:CallerId]]

HTTP Method

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

URL Parameters The integration automatically includes these query parameters:

• key: Your Retreaver RTB authentication key
• publisher_id: Your Publisher ID
• caller_number: Dynamic caller ID from [[tag:CallerId]]

JSON Request Body The integration sends an empty JSON object {} in the request body as required by Retreaver's RTB API.

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 campaign reservation status using the status field:

• Field: status
• Condition: Equals
• Value: reserved

This configuration accepts bids when Retreaver responds with a "reserved" status, indicating a successful campaign reservation.

Bid Response Handling

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

• Property Path: Enter the JSON path to the bid data
• Common Fields:
• • status - Response status indicating bid acceptance
  • campaign_id - ID of the campaign that accepted the bid
  • target_number - Phone number where the call should be routed
  • payout - The payout amount for the call

Testing Your Configuration

To test your integration:

1. Fill in your RTB Key and Publisher ID
2. In the webhook testing section, provide test values:
3. • tag:CallerId: Enter a test phone number (e.g., 5551234567)
3. Click Run Webhook to test the connection
4. Verify the test passes and shows a proper bid response from Retreaver
5. Confirm the acceptance parsing works correctly with the response

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

1. Bid Request: CallGrid sends call information to Retreaver's RTB endpoint
2. Campaign Evaluation: Retreaver evaluates the call against available campaigns
3. Bid Response: Retreaver responds with campaign reservation status 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 campaign's target number

Bid Response Structure

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

{

  "status": "reserved",

  "campaign_id": "12345",

  "target_number": "18005551234",

  "payout": 25.50,

  "caller_number": "5551234567",

  "publisher_id": "pub123456",

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

}

Response Status Values

Common Status Responses

• reserved: Campaign successfully reserved - call should be routed
• no_match: No matching campaigns available for this call
• rejected: Call rejected due to campaign criteria
• error: System error occurred during bid processing

Advanced Configuration Examples

Example 1: Basic Status Acceptance

Acceptance Criteria:

• Field: status
• Condition: Equals
• Value: reserved

This configuration accepts calls only when Retreaver reserves a campaign.

Example 2: Minimum Payout Threshold

Acceptance Criteria:

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

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

Example 3: Campaign Validation

Acceptance Criteria:

• Field: campaign_id
• 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 successful status and minimum payout:

Criteria 1:

• Field: status
• Condition: Equals
• Value: reserved

Criteria 2:

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

Advanced Use Cases

Multi-Publisher Strategy

Configure multiple CallGrid destinations, each targeting different Retreaver publisher IDs to maximize coverage and revenue optimization.

Campaign Performance Tracking

Use campaign ID data to track performance across different Retreaver campaigns and optimize routing strategies.

Payout Optimization

Leverage payout information to route calls to campaigns offering the best revenue potential.

Troubleshooting

Common Issues

Authentication Failures

• Verify your RTB Key is correct and current
• Ensure your Retreaver account has RTB permissions
• Check that the RTB Key has not expired

Invalid Publisher ID

• Confirm your Publisher ID exists in your Retreaver account
• Verify the Publisher ID is active and properly configured
• Check that the ID format matches Retreaver's requirements

No Campaign Matches

• Ensure there are active campaigns in your Retreaver account
• Verify campaign criteria match your call characteristics
• Check that campaigns have available capacity and budget

Status Response Issues

• Monitor response status values to understand bid outcomes
• Check campaign targeting settings in Retreaver
• Verify call quality meets campaign requirements

Testing the Integration

Template Configuration Test:

1. After entering RTB Key and Publisher 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)
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 status acceptance conditions

Best Practices

Campaign Optimization

• Monitor campaign performance metrics to optimize targeting
• Ensure call quality standards meet campaign requirements
• Track conversion rates across different campaigns

Revenue Maximization

• Set competitive but realistic payout thresholds
• Monitor campaign availability and adjust routing accordingly
• Track performance metrics to identify high-value campaigns

Call Quality Management

• Maintain high call quality standards to ensure campaign approval
• Monitor call completion rates and campaign feedback
• Implement quality controls to protect campaign relationships

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