# 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

```bash
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:

| Response field      | Tag                                     |
|---------------------|-----------------------------------------|
| `status`            | `retreaver_rtb_{buyer_id}_ping_status`  |
| `inbound_number`    | `retreaver_rtb_{buyer_id}_number`       |
| `retreaver_payout`  | `retreaver_rtb_{buyer_id}_bid`          |
| `retreaver_seconds` | `retreaver_rtb_{buyer_id}_timer`        |
| `retreaver_availability_count`   | `retreaver_rtb_{buyer_id}_count`        |

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.