Integrating Your Lead Vendor with AgentTech: A Developer's Guide
Your lead vendors generate the calls. AgentTech routes them to the right agents. But connecting those two systems—reliably, in real time, with proper attribution—is where most call centers hit friction. This developer-focused guide walks through every integration point between your lead vendors and AgentTech Dialer: the Queue Availability API for capacity checks, SIP routing for call delivery, Retreaver and Ringba connections for pay-per-call networks, webhook configuration for real-time event data, and practical API examples you can copy into your codebase today.
Integration Architecture Overview
Lead vendor integration with AgentTech follows a three-layer architecture: availability checking, call routing, and event reporting. Each layer operates independently, meaning you can implement them incrementally—start with availability checks, add SIP routing, then layer on webhooks for attribution and reporting.
Three Integration Layers
- Layer 1 — Availability: The Queue Availability API lets vendors check agent capacity before routing a call
- Layer 2 — Routing: SIP trunks and DID numbers deliver calls into the correct AgentTech queues
- Layer 3 — Events: Webhooks push real-time call data back to vendors for attribution, billing, and optimization
For a high-level understanding of how the Queue Availability API works conceptually, start with our Queue Availability API overview. This guide focuses on the hands-on implementation details.
Queue Availability API Integration
The Queue Availability API is a public REST endpoint that returns real-time agent capacity for any Publisher Queue. It's the first thing your lead vendor should integrate—before they ever route a call—because it prevents wasted spend on calls that no agent is available to answer.
GET https://dialer.agenttech.io/api.php?action=get_queue_availability&queue=vendor-name
{ "available_agents": 5, "total_agents": 12, "availability_pct": 41.67, "queue_name": "vendor-name", "status": "available"}
Polling Best Practice
Poll the availability endpoint every 15–30 seconds during active hours. Cache the response locally and use the cached value for routing decisions between polls. Polling more frequently than every 10 seconds provides negligible benefit and may trigger rate limiting. If you need sub-second accuracy, contact our engineering team about WebSocket availability streams.
Caller ID Filtering
Adding the optional callerid parameter enables state-based and skill-based filtering. When you include the caller's phone number, AgentTech looks up the area code, determines the caller's likely state, and returns availability only for agents licensed or skilled to handle calls from that state.
GET https://dialer.agenttech.io/api.php?action=get_queue_availability&queue=vendor-name&callerid=3055551234
{ "available_agents": 3, "total_agents": 8, "availability_pct": 37.5, "caller_state": "FL"}
SIP Routing Setup
Once your vendor knows agents are available, the call needs to reach your AgentTech queues. SIP (Session Initiation Protocol) trunking is the standard method for delivering voice calls from external systems. AgentTech supports inbound SIP connections from any standards-compliant provider.
DID Number Assignment
Assign dedicated DIDs (Direct Inward Dialing numbers) to each lead vendor or campaign. This enables per-vendor call tracking and makes routing rules vendor-specific.
Queue Mapping
Map each DID to a specific Publisher Queue in AgentTech. Calls arriving on that DID are automatically routed to the agents assigned to that queue.
SIP Header Passthrough
AgentTech preserves custom SIP headers from your vendor, enabling metadata like campaign IDs, sub-IDs, and source tags to flow through to your reporting.
IP Whitelisting
Lock down SIP access to whitelisted IPs from your approved vendors. Only traffic from authorized SIP endpoints reaches your queues.
Codec Compatibility Warning
Ensure your vendor's SIP trunk supports G.711 (PCMU/PCMA) codec. While AgentTech supports multiple codecs, G.711 provides the best audio quality for compliance-sensitive calls and avoids transcoding latency. If your vendor uses G.729 or Opus, contact our team to verify compatibility before going live.
Retreaver and Ringba Connection
Retreaver and Ringba are the two most popular call tracking and routing platforms in the insurance lead space. Both support real-time availability checks and SIP-based call delivery, making them natural integration partners for AgentTech. Here's how to connect each platform.
Retreaver Integration
Retreaver Setup Steps
Create a new buyer target pointing to your AgentTech DID number. Set the target type to "SIP" and enter the SIP URI provided by your AgentTech admin.
In Retreaver's buyer settings, add a pre-route webhook that polls the AgentTech Queue Availability API. Configure the target to only receive calls when available_agents > 0.
Map Retreaver's campaign tags (publisher_id, sub_id, campaign) to SIP headers or URL parameters so they're captured in AgentTech's call records for attribution.
Add your AgentTech webhook postback URL in Retreaver to receive call disposition data (connected, duration, conversion) back for revenue attribution.
Ringba Integration
Ringba follows a similar pattern but uses its own terminology. Ringba's "Buyer" concept maps to your AgentTech queue, and its "Ping Tree" feature can integrate the Queue Availability API for real-time capacity-based routing.
Ringba Ping Tree Configuration
Configure Ringba's Ping Tree to query the AgentTech availability endpoint before each call route. Set the ping URL to your queue's availability endpoint and configure the success condition to check that status == "available". If the ping fails or returns unavailable, Ringba automatically routes the call to the next buyer in the tree, ensuring zero wasted connections.
Webhook Configuration
Webhooks provide real-time, push-based event notifications from AgentTech to your external systems. Instead of polling for call status updates, AgentTech sends HTTP POST requests to your endpoint as events occur—call answered, call ended, call transferred, disposition set, and more.
{ "event": "call_completed", "call_id": "c_8f3a2b1d", "queue": "vendor-name", "caller_id": "+13055551234", "agent_id": "agent_42", "duration_seconds": 347, "disposition": "sale", "recording_url": "https://..."}
Supported Events
- call_answered
- call_completed
- call_transferred
- call_abandoned
- disposition_set
- recording_ready
Configuration Options
- Custom endpoint URL per vendor
- HMAC signature verification
- Retry logic (3x with exponential backoff)
- Event filtering by type
- Custom header injection
- Queue-specific webhook routing
Practical API Examples
Here are copy-paste-ready code examples for the most common integration scenarios. These examples use standard HTTP libraries and can be adapted to any language or framework.
Python — Availability Check with Caching
import requests, time# Cache availability for 15 seconds_cache = {}def check_availability(queue, caller_id=None): key = f"{queue}:{caller_id}" if key in _cache and time.time() - _cache[key]['ts'] < 15: return _cache[key]['data'] params = {"action": "get_queue_availability", "queue": queue} if caller_id: params["callerid"] = caller_id resp = requests.get("https://dialer.agenttech.io/api.php", params=params) data = resp.json() _cache[key] = {"ts": time.time(), "data": data} return data
Node.js — Webhook Receiver
const express = require('express');const app = express();app.use(express.json());app.post('/webhooks/agenttech', (req, res) => { const { event, call_id, duration_seconds, disposition } = req.body; if (event === 'call_completed') { // Update your CRM or billing system console.log(`Call ${call_id}: ${duration_seconds}s, ${disposition}`); } res.status(200).json({ received: true });});
Troubleshooting Common Integration Issues
Even well-planned integrations hit snags. Here are the most common issues developers encounter when connecting lead vendors to AgentTech, along with solutions:
Check the queue name parameter—it must exactly match the Publisher Queue name in AgentTech (case-sensitive). Also verify agents are assigned to the correct queue, not just logged into the dialer.
Verify that your vendor's SIP IP is whitelisted in AgentTech settings. Check that the DID in the SIP INVITE matches a configured number in your account. Confirm firewall rules allow traffic on ports 5060 (SIP) and 10000-20000 (RTP).
Confirm your webhook URL is publicly accessible (not behind a VPN or localhost). Verify the endpoint returns a 200 status code within 5 seconds. Check the AgentTech webhook logs for failed delivery attempts and error messages.
This is almost always a NAT/firewall issue blocking RTP media packets. Ensure your vendor allows symmetric RTP and that UDP ports 10000-20000 are open bidirectionally. Switch to G.711 codec if you're using a compressed codec.
For scaling strategies once your integration is live—including handling traffic spikes, multi-queue load balancing, and geographic routing—see our guide on scaling your inbound call center. And for advanced click-to-call attribution using number pools, check out our number pooling and click attribution guide.
Conclusion: Build Once, Scale Forever
A well-architected lead vendor integration is a force multiplier for your call center. When your vendors can check availability in real time, route calls via SIP with proper attribution, and receive instant webhook notifications on call outcomes, you eliminate wasted spend, maximize agent utilization, and give your vendors the data they need to optimize their campaigns for your benefit.
The integration patterns in this guide—availability polling, SIP routing, Retreaver/Ringba connections, and webhook event streaming—are designed to be implemented incrementally. Start with the availability API, prove out the connection, then layer on the remaining components. Each layer adds value independently, so you don't need to build everything before seeing results.
Ready to Connect Your Lead Vendors?
AgentTech Dialer provides a public availability API, SIP routing, Retreaver/Ringba integration, and real-time webhooks—all out of the box. Start your integration today.
Try AgentTech Dialer Now