Often a call buyer does not pay based on call-duration, rather they pay 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.
To facilitate this process, Retreaver introduces the concept of call keys. Call keys are special API keys that are uniquely associated with a call. In conjunction with the call's UUID, the call key grants the holder the ability to update calls via our set_value Call API.
You can pass call UUIDs and keys to your buyers via webhook or through SIP headers.
Passing the call UUID and key to a buyer
Method 1: via webhook, for buyers not using SIP
Adding an "answered" ping Webhook.
To add an answered ping, scroll to the "Webhooks" section of your campaign configuration. Click the green plus to add a new webhook group and set the trigger type to "answered".
To ensure the webhook is only triggered for calls routed to a specific buyer, use the Wizard to tag the webhook with your buyer's
system_buyer_id. This webhook will now only be triggered for calls that have been accepted by the given buyer.
Your buyer will need to provide you with an HTTP endpoint capable of receiving and processing the request. Use replacement tokens to designate where the call UUID -
[call_uuid] - and key -
[call_key] - will be inserted in the URL.
You will need to work with your Buyer to determine the format of the URL itself, at minimum they will need the call UUID and key to pass data back to Retreaver. They will most likely also need the caller ID of the caller so they can correlate the call with the correct contact record in their systems.
Method 2: via SIP header
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-RetreaverKey in the SIP INVITE, and store these values for later use.
Adding tags to calls via our call API
Now that your buyer has the call UUID and key, they can make API requests to Retreaver to add tags to calls.
Have your buyer replace CALL_UUID and CALL_KEY with the actual values that we passed to them. To add tags to the call, simply append additional URL parameters...
Calling the above URL (via GET, POST, or HEAD) will result in the call being tagged
tag2:value2. Your buyer can call this endpoint repeatedly to add additional tags to the call.
Informing Retreaver of a conversion
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 value or using a string-matching conversion trigger with a pre-set revenue and payout.
Using a posted-back revenue value
Configuring a postback conversion with posted-back revenue value.
The Postback Timeout field defines how many seconds after the call ends Retreaver should wait before deeming the call non-converted. Retreaver waits until a postback is received or the timeout is reached before firing any post-call webhooks.
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:
Simply replace CALL_UUID and CALL_KEY with the corresponding values, and set the revenue parameter to the amount being paid by the buyer.
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
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.
Configuring a postback to be triggered by a specific string in the URL.
Given the above example, your buyer would need to make a request to the following URL to trigger a conversion:
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.
Setting an appropriate postback timeout
When using postback conversions, all post-call webhooks 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 webhooks will be processed. If a conversion value is posted back after this happens, we'll mark the call as converted and process any conversion webhooks.
In cases where tag 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.