Connect Retreaver · InboundX docs

Add InboundX as a buyer

In Retreaver, add a new buyer for InboundX (some platforms call it a target) and choose the ping type, so Retreaver asks us before it sends each call.

From Retreaver's documentation Quoted as the platform documents it.

Where to add itDocumented: Edit Campaign → Webhooks → green Add → trigger → Webhook URL → Update Campaign. Buyer webhooks can also perform RTB pings.
The request editorDocumented: Webhook Configurator template dropdown; Auto-setup buyer tags exposes Call Buyer. Advanced configuration uses ping_url, ping_method, ping_headers, ping_data and ping_output_map.

Edit Campaign › Webhooks › green Add › trigger › Webhook URL › Update Campaign

Name

InboundX

Type

RTB ping

Ping URL

Number

Illustration: the menu path is from Retreaver's documentation; the screen may look different.

Paste your ping URL

Put this in the buyer's ping URL. Your key goes where the sample key is, and Retreaver fills in the bracketed tokens on every call.

Ping URL

https://app.inboundx.io/api/rtb/ping?key=YOUR_PING_KEY&caller_number=[caller_number]&caller_state=[caller_state]&request_id=[call_uuid]

Keep the key secret: anyone who has it can ping as you.

Not confirmed for Retreaver. Where this goes in Retreaver's screens isn't documented. What its documentation does say is below; confirm the screen with Retreaver.

From Retreaver's documentation Quoted as the platform documents it.

Request methodsDocumented: GETPOST
When it pingsDocumented: Use Passthrough/Pass-through Ping when forwarding upstream RTB requests; Start waits for an actual call.
Caller number tokenDocumented: [caller_number]
Caller state tokenDocumented: [caller_state]
Caller ZIP tokenDocumented: [caller_zip]
Other tokensDocumented: call_secret: [call_key]selected_buyer: [handler_id]
Call ID tokenDocumented: [call_uuid]
Call ID at ping timeNot confirmed: confirm with Retreaver

Accept only when we bid

Tell Retreaver how to read our answer. We answer reserved in status when we take the caller; anything else means don't send the call.

Accept the bid when this field

status

equals

reserved

Price field

payout

Retreaver bids also carry retreaver_payout and retreaver_seconds with the same values.

Not confirmed for Retreaver. Where this goes in Retreaver's screens isn't documented. What its documentation does say is below; confirm the screen with Retreaver.

From Retreaver's documentation Quoted as the platform documents it.

How it reads our answerDocumented: Valid JSON response keys become call tags; configurator PingOutputMap and output modifiers can map payout and timer values to buyer tags/routing/conversion criteria.
Fields its built-in template readsDocumented: retreaver_payoutretreaver_secondssip_addressinbound_numberexpires_atuuid

Type our address by hand

In the buyer's dial field, type the address from your setup message exactly, with sip: in front and a real @.

Send the call to

sip:YOUR_ROUTE@ADDRESS_FROM_YOUR_SETUP

This one is a sample. Copy yours from your setup message or the portal's Setup page.

Don't dial the platform's address tag

Retreaver offers a tag for the address and URL-encodes it, so the @ becomes %40 and the call goes to an address that doesn't exist. Type the address instead.

Typed by hand: reaches ussip:YOUR_ROUTE@ADDRESS_FROM_YOUR_SETUP

What the tag dials: never arrivessip:YOUR_ROUTE%40ADDRESS_FROM_YOUR_SETUP

Not confirmed for Retreaver. Where this goes in Retreaver's screens isn't documented. What its documentation does say is below; confirm the screen with Retreaver.

From Retreaver's documentation Quoted as the platform documents it.

A fixed SIP addressDocumented: Buyer profile Number accepts sip:{SEND_CALL_TO}. SIP Username and SIP Password are separate optional authentication fields.
The SIP address from each bidNot confirmed: confirm with Retreaver
The sip: prefixNot confirmed: confirm with Retreaver
How it treats the @Not confirmed: confirm with Retreaver

Keep the caller's own number

Leave the caller ID as the caller's own number, and send the call within 15 seconds of our bid. We match the call to its bid by that number: your own number, or a hidden one, won't match.

Not confirmed for Retreaver. Where this goes in Retreaver's screens isn't documented. What its documentation does say is below; confirm the screen with Retreaver.

From Retreaver's documentation Quoted as the platform documents it.

Passing the caller ID throughNot confirmed: confirm with Retreaver
Ping timeoutDocumented: seconds: 5
The caller's number on a SIP transferNot confirmed: confirm with Retreaver

Don't convert on call length

This campaign pays when the call qualifies, not after a number of seconds. Turn off any duration conversion for InboundX in Retreaver, and ignore seconds in our bid. The postback in the next step tells Retreaver which calls paid.

Ignore this bid field

seconds

Not confirmed for Retreaver. How Retreaver turns off a duration conversion isn't confirmed. Confirm with Retreaver that only the postback marks a call as paid.

Tell your platform which calls paid

When a call pays, we call a URL on your platform with these tokens filled in. Here's where to find that URL:

In Retreaver, open your conversion postback key and copy its URL. Put {PHONE} where it says CALLER_NUMBER, {PAYOUT} as the value and {CALL_ID} as call_uuid.

Your call ID

{CALL_ID}

What the call earned, in US dollars

{PAYOUT}

The caller's number

{PHONE}

It should end up like this

https://your-platform.example/conversion?call={CALL_ID}&phone={PHONE}&payout={PAYOUT}

Required: it's the only way Retreaver learns which calls paid.

From Retreaver's documentation Quoted as the platform documents it.

Where conversions are set upDocumented: Buyer → Postback Keys → Add Key → Conversion; configure campaign Postback conversion criteria with the buyer tag.
Conversion URL templateDocumented: https://retreaverdata.com/postbacks/{POSTBACK_KEY}?caller_number={PHONE}&call_uuid={CALL_ID}&value={PAYOUT}
Conversion request methodDocumented: POST

Buyer › Postback Keys › Add Key › Conversion

Name

InboundX

Conversion URL

https://your-platform.example/conversion?call=…

Illustration: the menu path is from Retreaver's documentation; the screen may look different.

Test my setup

One test ping through your Retreaver setup. We show what arrived, and what to change, as it happens.

Test my setupNo login

Not started

Check your Retreaver setup with one test ping

We'll give you a temporary ping URL. Put it in your platform in place of your real one, call your tracking number from any phone, and see what arrived, in plain words.

Your ping arrives
waiting
The caller's number is filled in
waiting
The caller's state is readable
waiting
Every field is under a name we read
waiting
The call arrives inside the hold
not tested yet
The call's caller ID matches the ping
not tested yet

Nothing is billed and no agent is held: every ping gets a test bid that can't be dialled.