Receiving Postback Data from Third Party Systems

Often a call buyer does not pay based on call-duration, rather they pay their publisher when an actual sale has occurred. In these cases, the call buyer needs to post data back to Retreaver to inform us that a conversion has happened.

In order to post back data for the call, we need to pass the Buyer the call UUID and call key. This can be done either by using a “Bridged” tracking URL that pings the Buyer, or by using SIP.

Passing the Call UUID and Key Via a Bridged Ping

bridged_ping

Adding a bridged tracking URL.

To add a bridged ping, edit your existing campaign, or include this at the bottom of the new Campaign creation screen. Under the Tracking URLs section, click on the green plus to add a new tracking URL and set the trigger type to ‘Bridged’. Use the Wizard to select your buyer, we advise against entering it manually. Ensure your Publisher and Buyer are selected. Add any desired [tokens] at the bottom.

To use a bridged ping, your Buyer must be capable of receiving information via an HTTP HEAD request, and you must add a bridged tracking URL to your Campaign. Tracking URLs that have the bridged trigger are fired when a call is connected to a Buyer. These callbacks are used to pass information to the Buyer.

You will need to work with your Buyer to determine the format of the URL itself, but they will need the call UUID and key to pass data back to Retreaver. They will most likely need the caller ID of the caller so they can correlate the call with the correct call UUID in their systems.

Passing the Call UUID and Key Via SIP

If your Buyer is using a SIP-based phone number, the call UUID and key will be automatically passed to them via SIP headers. They should look for headers named X-PH-RetreaverUUID and X-PH-RetreaverKey in the SIP INVITE, and store these values for later use.

Posting Data Back to Retreaver

In order to track conversions based on data posted back to us, you’ll need to have a postback conversion group defined for your Campaign. There are two ways you can implement conversion postbacks, either using a posted-back revenue, or using a conversion trigger with a pre-set revenue and payout.

Using a Posted back Revenue Value

postback

Configuring a postback conversion.

Be sure to allow enough time in the Postback Timeout after the call ends for the Buyer to post back before this call is counted as a non-conversion.

The Buyer can use the UUID and call key to update the conversion value on the call by making a request to the following URL:
http://retreaver.com/calls/[call_uuid]/set_value?key=[call_key]&revenue=10.00

Simply replace [call_uuid] and [call_key] with the corresponding values, and set the revenue parameter to the revenue that will be set on the call.

In cases where you are not paying a publisher, set the payout to zero by setting the modifier to *0.

In order to derive the payout from the revenue that is posted back, you can set a modifier in the “posted-value payout modifier” field. The string that you enter in the field will be evaluated operation-by-operation from left to right, and the operators can include * (multiplication), / (division), (subtraction), and + (addition). In order to multiply the value posted back by 0.8, enter *0.8 in the field. For a call with $10.00 in revenue, this would cause the payout to be set to $8.00.

If the modifier field is left blank, the payout will be set to the revenue amount, which is likely not what you want. In cases where you are not paying a publisher, set the payout to zero by setting the modifier to *0.

Using a Conversion Trigger with a Static Revenue and Payout

Perhaps you have a call buyer that has agreed to pay you a certain price, but they simply want to post back to you whether or not there has been a sale. In this case, you can configure a Postback conversion to use a “conversion trigger”, a string that we will look for in the postback request URL from your buyer.

postback2

Configuring a postback to be triggered by a specific matching string.

Given the above example, your buyer would need to make a request to the following URL to trigger a conversion:
http://retreaver.com/calls/[call_uuid]/set_value?key=[call_key]&sale=true

Your buyer will need to replace the call UUID and call key with the correct values and send an HTTP request to the URL. We will then detect that a conversion has occurred and set the static revenue and payout on the call.

Configuring the Postback Timeout

When using Postback conversion settings, all tracking URLs are delayed until it has been decided whether or not the call has converted. By default, a timeout of 10 minutes after the call ends is set. If we don’t receive a postback from your Buyer, the call will be counted as non-converted and any non-conversion tracking URLs will be processed. If a conversion value is posted back after this happens, we’ll mark the call as converted and process any conversion tracking URLs.

In cases where data is posted back that doesn’t cause a conversion to be triggered, a non-conversion will still not be triggered until the postback timeout expires.

Jason Kay

Jason Kay is the CTO and co-founder of Retreaver.