Retreaver + VICIdial tag-based call routing

When teams ask us for this

You route by tag and answer in-house

Retreaver decides which buyer wins on tags, then sends the call to a destination on your box.

You need the tags on the agent screen

Tags cross either as SIP headers on the call or ahead of it as a webhook that creates the lead.

You want the record to exist before the call arrives

The webhook path calls add_lead ahead of the call, so the screen is populated even if a carrier strips headers in transit.

You already use Retreaver with a CRM

Retreaver publishes CRM and affiliate integrations but names no dialer. The destination end is the piece nobody has written down.

Retreaver is call tracking and tag-based routing. It decides which buyer wins a call, then sends it to a destination. Point that destination at your VICIfast box and the call lands in a VICIdial in-group with the tags attached.

Retreaver publishes integrations with Everflow, MediaAlpha, Pipedrive and ActiveProspect among others. It lists no dialer, PBX or contact-centre integration at all. That gap is why this page exists: the routing is documented and stable, but nobody has written down how the destination end works when the destination is VICIdial.

Integrations on demand. We are not a Retreaver partner and there is no connector to enable. Our team wires it as scoped work, quoted per setup.

Tags are the whole model

Retreaver attaches key-value tags to a call - the number that was dialled, the campaign, the publisher, whatever the affiliate passed in. Routing rules match on tags. Everything useful about the call is a tag before it ever reaches you.

Two ways those tags cross over:

On the call, as SIP headers. Read them in the dialplan with PJSIP_HEADER(read,...) and populate the lead before the screen paints.

Ahead of the call, as a webhook. Retreaver fires the tag set to a URL you nominate. An endpoint receives it, calls non_agent_api.php with function=add_lead or update_lead, and the record exists before the call arrives.

The webhook path is more work and more robust. Headers can be stripped by a carrier in the middle; an HTTP POST either arrived or it did not.

Setup

Create the in-group and agent skill that will answer the traffic.
Create the SIP endpoint or DID for Retreaver to target.
Add the number as a Target in Retreaver and attach it to the campaign's routing rules.
Decide which tags matter to the agent and agree their names.
Map tags to VICIdial fields, either in the dialplan or in the webhook endpoint.
Test with live traffic and confirm the tags survive the whole path.

It also runs the other way

Everything above is traffic arriving. The dialer can call Retreaver as well: VICIdial fires their API mid-call with the lead substituted into the URL, and the caller is transferred live if Retreaver accepts. Retreaver routes on tags, so the accept can name a different destination per buyer without you changing anything.

A transfer accepted during the conversation is worth considerably more than a record posted after it, and it is a separate piece of work from the inbound path. See live transfer on a buyer API response for the hooks and the failure modes.

Gotchas

Tag names are yours to keep stable. Rename a tag in Retreaver and the dialplan reads an empty string. Nothing errors; the agent screen is just blank where the publisher used to be.

Duplicate webhooks. Retreaver can fire on more than one event. Make the endpoint idempotent on the call identifier or you create two leads for one call.

Retreaver's timeout versus your ring time. Same clock problem as every call platform. Their routing gives up and tries the next buyer while your agent is still ringing.

Questions we get asked

Are you a Retreaver partner?

No. Retreaver lists no dialer integration at all, which is exactly why this page exists. We wire the destination end as scoped work, quoted per setup.

Headers or webhook - which is better?

The webhook is more work and more robust. Headers can be stripped by a carrier in the middle; an HTTP POST either arrived or it did not.

What happens if a tag is renamed?

The dialplan reads an empty string and the agent screen is blank in that spot. Nothing errors, which is what makes it easy to miss.

Can Retreaver fire the webhook twice?

Yes, it can fire on more than one event. The endpoint is made idempotent on the call identifier so one call does not become two leads.

Does this work with my existing routing rules?

Yes. The routing stays entirely on their side. Only the destination changes.