Help Your Publishers Send You Calls That Connect

Why this matters

When a publisher pings your campaign over RTB, we reserve one of your buyers and return its bid. A classic ping-post setup then expects the publisher to send a second request — the post, or confirmation — before sending the call. In practice there is rarely time for it: the caller is already on the line. So many publishers skip the confirmation and send the call straight after the ping.

That is where calls get lost. By the time the call arrives, the buyer reserved for it may be busy, and the call doesn’t connect.

Publishers see every call that doesn’t connect. They watch the performance of each campaign they send to, and when yours goes down, they send their calls somewhere else.

What’s new

You can now tell your publishers how many of your buyers are available for a caller. Turn on Return retreaver count on the RTB postback key you give a publisher, and every successful (reserved) response includes retreaver_availability_count: the number of your buyers that could take this caller right now, including the reserved one.

With that number, a publisher can send the call directly — no confirmation ping — when more than one buyer is available, and confirm first or hold the call when only one is. If the reserved buyer doesn’t answer, the call moves on to the next available buyer, so calls sent with two or more buyers available have a much better chance to connect. This can drastically improve the performance your publishers see for you.

It’s an addition, not a change: the ping works exactly as it does today, confirmation still works for publishers who use it, and keys without the setting are unaffected. You choose per key which publishers get the count.

How the count relates to payout and seconds

• retreaver_payout and retreaver_seconds are still the bid of the reserved buyer — the first one matched, exactly as today.
• retreaver_availability_count includes that reserved buyer. A count of 3 means the reserved buyer plus 2 others.
• The other buyers may pay a different amount and need a different number of seconds; the response doesn’t describe them.
• The call always goes to the reserved buyer first. The others are only tried when it doesn’t answer:
  • with “Route only to reserved Buyer” on the key (called “Route only to reserved Endpoint” in some accounts), they are never tried — the count is still returned, but there is no next buyer to fall back to;
  • on campaigns that convert on the call attempt, an unanswered call ends instead of moving on.
• The count is a snapshot of this moment, not a guarantee.

The count is specific to the caller: a caller who is suppressed, or whom a buyer’s caller list or geo filter excludes, only counts the buyers they could actually reach. Like retreaver_payout and retreaver_seconds, it’s only on reserved answers — no-target and rejected answers look exactly as they do today.

How to use it

curl "https://rtb.retreaver.com/rtbs.json?key=YOUR_KEY&caller_number=..."
# => {
#      "uuid": "...",
#      "status": "reserved",
#      "inbound_number": "+15555550123",
#      "sip_address": "sip:...@sip.rtb.retreaver.com",
#      "expires_at": "...",
#      "retreaver_payout": 1.5,
#      "retreaver_seconds": 60,
#      "retreaver_availability_count": 3
#    }

For example, a publisher sends the call directly when retreaver_availability_count is 2 or more, and confirms first — or sends the call elsewhere — when it’s 1.

When your publisher is also on Retreaver

A publisher that pings you from its own Retreaver account sets up the ping with the webhook configurator’s “Retreaver RTB - Ping” template. It stores your answer in tags prefixed with retreaver_rtb_{buyer_id}_, where {buyer_id} is the Retreaver system ID of the buyer that represents you in their account:

They then tag that buyer with numeric conditions to decide when it gets the call. For buyer 12345:

• retreaver_rtb_12345_count >= 2 — at least 2 of your buyers are available
• retreaver_rtb_12345_bid > 17 — the reserved buyer pays more than 17

With both tags, the call goes to you only when the payout is above 17 and at least 2 of your buyers can take it. Webhooks created from the template before this release need "count":"retreaver_availability_count" added to their output map.

Important: retreaver_rtb_12345_bid and retreaver_rtb_12345_timer are only for the first matched buyer — the one reserved for the call. The other buyers counted in retreaver_rtb_12345_count may pay a different amount and need a different number of seconds. If the call ends up with the second buyer, the payout and the seconds needed to convert can differ from what the ping returned.

How you’ll know it’s working

Look at the same thing your publishers look at: how many of the calls they send you connect. Your existing call reporting shows connected calls per campaign and publisher. Compare the connect rate and connected-call volume from a publisher before and after they start using retreaver_availability_count.

Permissions

Same access as the rest of RTB: you need a postback key with real-time bidding enabled on the campaign. No new permission is required — Return retreaver count is on the same postback key form as the rest of the key’s RTB settings.