Viewing External Activities in Oracle Eloqua

August 5, 2014 | Jason Kay

Retreaver automatically attempts to map calls to Eloqua contacts. This is most accurately and consistently accomplished when our Marketing AppCloud component is configured to track at a Contact Level Tracking Resolution.

When we’re able to map a call to an Eloqua contact, we add External Activities for different phone-based events. These events include a contact calling in, a call being connected to a Contact Handler, a call converting, and a call ending.

Customizing conversion criteria

The call conversion event is perhaps the most relevant event for marketers. Using this event you can accurately gauge consumer engagement, measure revenue, and track sales back to the responsible campaign and landing page.

You can create many different types of conversions in Retreaver and track them separately in Eloqua.

Customizing conversion settings in Retreaver

To track conversion events, you’ll need to define new conversion criteria on your campaign in Retreaver. Navigate to your campaign, and click the Add button in the Conversion Criteria section to add a conversion group.

Name the conversion group according to whatever naming conventions you use elsewhere in Eloqua.

How Conversion Matching Works

When a call ends we evaluate your conversion groups in order, looking for the first conversion group whose tags match those on the call. The first conversion group that matches the call is used, regardless of whether the call meets the conversion criteria defined in the group.

We then evaluate if the call “converted” according to the conversion criteria. For a conversion group that is timer based, we use the highest timer that the call met or exceeded.

For postback based conversion groups, we wait until we receive a postback from your call center. If no postback is received we mark the call as not converted.

Tag the conversion group in such a way as to ensure that it only matches calls you want it to match. In the screenshot above, we’ve tagged the group with dialed_call_duration:>=600. This will ensure that only calls which were over 10 minutes long, and thereby meet the 600 second conversion criteria will match the group. Other calls will fall through to the default conversion criteria, with a timer of 60 seconds, below.

A common usage of this feature is to set different conversion criteria depending on the Contact Handler a call is routed to. Simply use our Tag Wizard to add a system_handler_id tag for your Handler. Only calls that have been routed to the Handler will match the conversion group, as calls are automatically tagged with the System Handler ID of the Handler they are routed to.

Viewing call activities on an Eloqua contact

Our live Eloqua landing page with call tracking configured.
Our live Eloqua landing page with call tracking configured.

Above is our “True Omnichannel Tracking in Eloqua” promotional landing page. I’ve placed a call to the number shown on the page to demonstrate what happens when a call converts.

The Retreaver call log view

The phone call I just placed, viewed in Retreaver.
The phone call I just placed, viewed in Retreaver.

After the call, navigating to the call from the call log, I can see the different tags that have been added to the call. I can also see that the call matched our “Default Conversion Settings” conversion group and converted according to the conversion criteria.

Viewing call activities in Eloqua

External Activities on the contact that called in.
External Activities on the contact that called in.

Navigating to my Eloqua contact, I can see the additions to the Recent Activity log. The log shows that a phone call has been made and that the call converted according to the Default Conversion Settings.

Conversion External Activities are named after your conversion group, with the word “conversion” appended.

When a call converts, Retreaver creates an external activity that is named after your conversion group, with the word “conversion” appended.

The contact's complete activity log.
The contact’s complete activity log.

From the Activity Log tab, all the activities related to the contact can be seen.

Viewing Reports on Call Activities in Eloqua Insight

While viewing activities on individual contacts may be useful for support purposes, marketers and executives alike want a higher level overview of actions contacts are taking.

Running reports in Insight

Step 1: Search

Searching for External Activity reports in Insight.
Searching for External Activity reports in Insight.

From the Insight interface, search for “external” in the search field in the upper right hand corner.

Step 2: Run

Running a report.
Running a report.

Select the time span you want to filter by, and then click run.

Step 3: Done

The External Activity Analysis report.
The External Activity Analysis report.

Your report is ready.

External Activities in Insight Analyzer

Selecting only conversion activities with a filter in Analyzer.

With Analyzer, you can use External Activities to create custom filters and reports. Analyzer makes it easy to generate reports for a subset of your activities, for instance, drilling down on calls that converted.

In the screenshot above, a filter has been created to select conversion activities only.

Segmenting Contacts based on Call Activities

Creating a segment for contacts who called in but didn't reach a Contact Handler.
Creating a segment for contacts who called in but didn’t reach a Contact Handler.

The call based external activities that Retreaver creates can be used to easily segment contacts who have previously converted, or perhaps who have received inadequate service.

In the above screenshot, the first filter selects all contacts who have called our campaign in the last 7 days. Then the second filter excludes all contacts whose call was connected to a Contact Handler. This segment could then be targeted for support outreach to improve customer service.

Next steps

Get more detailed call information with an Eloqua Custom Object

Configuring a Custom Object to receive call information in Eloqua

| Jason Kay

While external activities provide excellent summary information about what happened in calls, custom objects can provide even more detail. Custom objects can receive any information you want to pass back in to Eloqua, and you can then run reports on them with Insight Analyzer.

Setting up a Retreaver Call custom object

Step 1: Create

Creating a new custom object in Eloqua.
Creating a new custom object in Eloqua.

Navigate to Custom Objects through the Contact menu in Eloqua. Click the New Custom Object menu option as shown.

Step 2: Configure

Configuring the new custom object.
Configuring the new custom object.

Name your new custom object “Retreaver Call”, and set the Entity Field to Eloqua Contact ID. Click Next.

Step 3: Add Fields

Adding a field to the new custom object.
Adding a field to the new custom object.

Add a field for each attribute you want posted back into Eloqua. If you want a field to be available in Insight Analyzer, you’ll have to add it as a Contact Field. Note that fields on the contact will always reflect the most recent Retreaver Call.

Adding a Revenue field.
Adding a recording URL field.

Adding Revenue and Recording URL fields.

Field Mapping

Your custom object will be filled in with data from Retreaver tags after each call completes.

Text Tags
The ID of the Retreaver campaign the call went through. Note: Use eloqua_campaign_id to access the Eloqua campaign ID. We recommend setting the Retreaver campaign ID to match the Eloqua campaign ID.
The Source ID of the party responsible for the call.
The first name of the Source responsible for the call.
The last name of the Source responsible for the call.
The company name of the Source responsible for the call.
The ID of the Contact Handler the call was routed to.
The sub-Source/affiliate ID responsible for the call.
The phone number the caller used to call in.
The Retreaver UUID for the call.
The secret key used to postback conversion information about the call.
The phone number of the caller as it appeared on Caller ID.
The caller’s city based on their phone number, or their precise city if they entered a zip code.
The caller’s state based on their phone number, or their precise state if they entered a zip code.
The zip code the caller entered, if any.
The country of the caller, based on their phone number or zip code.
The number of the Contact Handler the call was routed to.
The URL of the MP3 recording for the call.
The status of the call when it ended.
Who hung up the phone first: caller or target (Contact Handler).
Whether the call converted.true or false. Note: This will be a boolean tag in an upcoming release.
Whether the call was a duplicate of a previous call.true or false. Note: This will be a boolean tag in an upcoming release.
The name of the conversion criteria that was used for the call.
Date-time Tags
When the caller called the trackable phone number.
When the caller was forwarded to a Contact Handler.
When the call ended.
Numeric Tags
The Retreaver internal Handler ID of the Contact Handler the call was routed to.
The number of seconds the caller was on the line with the Contact Handler.
The total duration of the call, from start to finish, in seconds.
The total number of minutes you were billed for the call.
The price per minute you were billed for the inbound call.
The price per minute you were billed for the outbound call.
The total cost you were charged for this call.
The conversion timer that was reached.
The amount earned on the call, according to the conversion settings.
The cost of the call, not including Retreaver charges, according to the conversion settings.

The fields have been added to the custom object.
The fields have been added to the custom object.

Click Next to continue.

Step 5: Headers

Adding header fields.
Adding header fields.

Configure header fields, then click Next to continue.

Step 6: Retreaver Field Mapping

The Custom Object is configured.
The Custom Object is configured.

Your Retreaver Call custom object is now configured in Eloqua. The last step is to configure the mapping between the Custom Object and Retreaver tags on Retreaver.

Login to your Retreaver account and navigate to your company settings page to continue.

Mapping Eloqua Custom Object fields to Retreaver tags.
Mapping Eloqua Custom Object fields to Retreaver tags.

Click the Integrations tab on your company page, then click the Custom Object Mapping tab.

Select the Retreaver Call custom object, and then for each custom object field, select the custom object field on the left, and the corresponding Retreaver tag on the right.

Click Update Eloqua company integration at the bottom to complete save your settings and complete this tutorial.

Viewing a Retreaver Call custom object

A custom object record that has been mapped to an Eloqua contact.
A custom object record that has been mapped to an Eloqua contact.

Navigating back to the Custom Object section of Eloqua, we can now see Retreaver Call records that have come in. The “Custom Data Object” has been mapped correctly to the Eloqua contact that placed the call.

If your contacts aren’t mapping correctly, make sure you have the Entity Field set to Eloqua Contact ID as described in step 2 above.

Reporting on Eloqua custom objects

Retreaver Call custom object in Eloqua Insight Analyzer.
With an Eloqua Insight Analyzer license, you can easily create new reports in Insight that utilize your Retreaver Call custom object.

After adding your Retreaver Call custom object, you need to follow the steps below to make the custom object data available in Insight.

Step 1: Setup

Setting up insight export.
Setting up insight export.

Navigate to the Custom Object area of the Contacts section in Eloqua, and then click the Custom Data Reporting Setup link from the menu seen above.

Selecting the Retreaver Call custom object.
Selecting the Retreaver Call custom object.

Click the button indicated by the red arrow above, select “Retreaver Call”, and then click the Include in Insight button as highlighted.

Step 2: Fields

Selecting Retreaver Call fields.
Selecting Retreaver Call fields.

Click the datacard icon Datacard Icon and the window above will pop up. Select the fields you want to report on in Insight, and click OK at the bottom.

Step 3: Save

Fields have been included in Insight.
Fields have been included in Insight.

Click the Save button at the bottom of the main screen, and you’ll see a message stating that it will take 10 minutes for the custom object to be updated in Insight.

Now you can create reports using your Retreaver Call custom object in Analyzer. When you select the Retreaver Call object in Analyzer, if you only see Date Created and Date Modified, you’ll have to wait for Analyzer to fully synchronize. The fields you added to Insight in step 2 will be available within 24 hours.

Adding call tracking to Eloqua landing pages

| Jason Kay

Adding the Retreaver call tracking component to your Eloqua landing page is simple. You must have the Call Tracking app activated in Eloqua.

Adding a Retreaver component to your Eloqua landing page

To get started, open the landing page you want to add a trackable phone number to for editing.

Step 1: View Source

View the source of your landing page.
View the source of your landing page.

Click the button highlighted above to toggle on the source code view. If you don’t see the button seen above in your Eloqua account, click here for instructions on enabling it.

Step 2: Place

Dragging the call tracking component into your landing page source.
Dragging the call tracking component into your landing page source.

Click the “Cloud Content” menu item on the left and find the Retreaver “Dynamic Number Insertion” component. Scroll to the bottom of your source code, and then drag and release the component right before the closing </body> tag.

Step 3: Configure

Edit the call tracking component to configure which phone numbers get replaced automatically.
Edit the call tracking component to configure which phone numbers get replaced automatically.

The Cloud Content Configuration window will automatically open. Here you can select which Retreaver campaign you want to use for this specific component, and set which phone numbers you want to be automatically replaced with Retreaver trackable numbers.

Retreaver campaigns hold settings for how we handle your phone calls. This includes customizations like greetings that are played to your callers, and settings for where we route your calls.

If you’ve never set up a Retreaver campaign before, read our tutorial about the Campaign Wizard and then come back to this page.

If you’re setting up a new campaign for this landing page, click the New Campaign Wizard button to go through the wizard. To use an existing campaign, select the campaign from the drop-down menu.

In the number replacement settings section, add any phone numbers that you want to be replaced with Retreaver trackable numbers. Enter the numbers exactly as they appear on your page, and we’ll match the formatting when inserting trackable numbers.

Step 4: Save

Save your changes.
Save your changes.

When you’re done, click Update Component to save your settings.

Step 5: Verify

The phone numbers on our landing page are being replaced correctly.
The phone numbers on our landing page are being replaced correctly.

Taking a look at the page at, we see that the integration is functioning correctly.

All the phone numbers on our page are being replaced with dynamic, trackable phone numbers from our Retreaver campaign.

Now would be a great time to call the number you see on your landing page, and verify that everything is working correctly.

Editing your call tracking settings

Editing Cloud Content components from Eloqua.
Editing Cloud Content components from Eloqua.

If you ever need to update the configuration of your Retreaver component, just double click the Retreaver graphic when editing your Eloqua landing page.

Next steps

Viewing calls as external activities in Eloqua
Get detailed call information with an Eloqua Custom Object

Add call tracking to Oracle Eloqua

| Jason Kay

If you’re not tracking phone calls, you’re missing a very large part of the marketing picture. You’re not being credited for sales and income that could be attributed to your marketing efforts, and you’re probably not even aware of the full impact of your campaigns.

You can easily track calls generated by your Eloqua campaigns by adding Retreaver to your Eloqua account.

Activate Retreaver in Oracle Eloqua now!

Activating Retreaver on your Eloqua account

To get started, click the Activate Retreaver in Eloqua button above.

Click Accept and Install
Click Accept and Install.

Click the Accept and Install button as seen above.

Click Sign In.
Click “Sign In”.

Click Sign In, and confirm that you want to install our component.

Click "Accept".
Click “Accept”.

Click “Accept” here to allow Retreaver to interact with your Eloqua account, completing the installation. A free Retreaver account will be automatically created for you if you don’t already have one.

Installation is complete.
Installation is complete.

Now you’re all set! Start adding call tracking to your Eloqua campaigns by adding the Retreaver “Dynamic Number Insertion” call tracking component to your uploaded landing pages via the landing page source editor, or to WYSIWYG landing pages.

Next steps

Add call tracking to your Eloqua landing page

Programmatic Call Initiation

July 1, 2014 | Jason Kay

Introduction to click-to-call

With Retreaver, you can initiate calls for your web visitors without any interaction on their part. These calls can be tied to their existing Retreaver session and any numbers that are being displayed on your landing pages, or they can be initiated via a server-to-server request.

Click-to-call can be used instead of choosing to display a trackable phone number to your visitors. Click-to-call works by collecting your visitor’s phone number and initiating a call to them programmatically. This is a great way to increase conversions, as it ensures your visitors get on the phone.

Click-to-call is perfect for users who want to track many different attributes, but don’t want to create large number pools. You can pass in unlimited tag values to associate with the call in your click-to-call initiation request.

Note: Click-to-call is different from tap-to-call, which is just using tel links to link a caller to a phone number.

Getting Started

Setting up your Campaign

Enabling click-to-call on a campaign. Click the image above to expand in size.

Once you decide to use click-to-call, you need to enable it on your campaign. Browse to your campaign and click the Toggles tab, then enable the click-to-call toggle.

Setting up Numbers

You must have at least one number associated with the campaign to use click-to-call. This number will be displayed on the visitor’s caller ID. If the person misses your call and calls back, they will still be routed to the proper Buyer as their new call will take on the properties of the missed call.

Initiating calls server-to-server

Send a JSON-formatted POST request to:[number_id].json
Replace [number_id] with the ID of the Retreaver number you want the call to come from.

In the request body, include a dial attribute that tells us which number you want us to call. You can also include any data you want associated with the call. You can use any attribute names other than reserved keywords.

The call UUID is returned to you and can be used via our API to get more information about the call, and to reference the call in the future.

If the request was not successful, error 500 will be returned.

This uses the same interface that our number display script uses to place calls through the browser.

Initiating calls through the browser

This documentation is for the deprecated insert.js. To initiate calls via Retreaver.js, see Retreaver.js – Calling a visitor.

You can programmatically trigger a call via our insert.js script if there is a Retreaver number displayed to the visitor and you know their phone number.

If you have more than one number displayed on a page, you must pass a ref parameter in the query string of the insert.js script. You can then use the value of this ref parameter to reference the number that we return.

In this case, you could also add a ref:capital-one tag to the Buyer that you want the call to be routed to if you also have multiple Buyers on the campaign.

To initiate a call, simply call the function.

The string phone number you want to dial to reach the consumer.
number_ref [optional]
The string ref value of the number you want to use to call the consumer, if you’re displaying multiple numbers on a page. This helps our script understand which number it should be using to place the call.
parameters [optional]
A JavaScript object with additional parameters to pass to Retreaver. This can include key:value pairs for tags, or any other data you want to use in the call. All of these additional parameters are available for use in our tracking URLs as replacement tokens.
callback [optional]
A callback function which will receive the result of the request to Retreaver, including the call UUID and status.

Crediting the correct Publisher

When the code says ‘affiliate’, it is referring to your Publisher.

For browser-initiated requests, we’ll automatically attribute the call to the Publisher associated with the displayed number.

If there is no Publisher associated with the number you wish to use to initiate a click-to-call call, you can pass an affiliate_id in. Pass the affiliate_id attribute in via the parameters field of your JavaScript function call, or in the body of your server-to-server POST.

In this way, you can avoid creating a separate number for each Publisher.

Influencing which Buyer we route the call to

You can influence which Buyer we route to by using our tag-based routing feature, or by using placeholder buyers/target maps.

When the code says ‘target’, it is referring to your Buyer.

Tag-based routing

Tag-based routing can be used to route the call to a Buyer that is already associated with a routing setting on the campaign.

If you’re using our number display script, we highly recommend that you make use of the ref tag to tag your Buyers, since that parameter is also needed if you’re displaying multiple Buyers on a page.

Otherwise, simply create a new tag without a prompt in Retreaver. You might call this new tag buyer.

In the parameters for the click-to-call initiation, include the tag key and value as an argument. You can include this in the body of your server-to-server request or in the parameters argument of your Javascript function call.

The call that’s created will be automatically tagged with target:capital-one. On a campaign without any prompts, the call will be routed directly to a Buyer in the “when 1 is pressed” scenario which is tagged withtarget:capital-one.

Secure Override: Buyer map

Placeholder Buyers are useful when you don’t know the number of the Buyer in advance, or when you can’t add all the Buyers to your Retreaver campaign.

You can configure your campaign with a placeholder Buyer and use our Secure Override feature to dynamically swap in a new Buyer number. To create a placeholder Buyer, simply create a new Buyer with a number ranging from 1 to 99.

Secure Override requires that you pass in two arguments with your click-to-call parameters: target_map in format original_target_number->new_target_number, and a checksum attribute named target_map_cs as described below.

If I have a placeholder Buyer with number 1 which I wish to map to 416-668-6980, my Javascript function call would look like this:

Calculating the target_map_cs checksum

We need to calculate the SHA1 hex digest of your target_map string joined with your API key. You can get your API key by clicking here.

Your API key should never be included in your web page’s source code or exposed to your visitors as it grants unfettered access to your Retreaver account!




Reserved keywords

Retreaver Results

June 14, 2014 | Jason Kay

For most lead generators, inbound sales calls are distributed to buyers on a 1-to-1 basis. Each caller is routed to a single buyer. But what if you could allow consumers to call all your buyers?

Introducing Retreaver Results

Retreaver Results is a new API that facilitates the display of individual trackable phone numbers for each Buyer on a campaign. The new Results functionality allows consumers to comparison shop, delivering fully qualified leads to multiple buyers.

Click Here to View our Demo Site

Retreaver Results follows all your existing business logic on Buyers, like business hours, caps, and tag filters. Ask your visitors for their zip code, and pass that information along to the results.js script to filter Buyers by geo. Any tags that can be used in the Retreaver system can be passed to Retreaver Results to determine the Buyers you want displayed.

Once the visitor dials in, they’ll be routed directly to the Buyers they chose, without any unnecessary IVR prompts.

Getting started

The results.js code. The show_key is specific to your campaign, retrieve it form your campaign page.

Simply add the results.js code to your thank you page, and append any tags you want to pass in via the query string. Above, we pass in the consumer’s zip code as 90210 so we only show Buyers that can take calls from their area.

For each Buyer you want to display, create a <div> element with ID matching cp-target-3410 where 3410 is the Retreaver system Buyer ID. You should wrap all the Buyer divs in a single parent div element. We’ll dynamically hide and re-arrange the cp-target divs depending on which Buyers can receive a call from the consumer, and with respect to your priority and weight settings.

If you’re using Buyer groups and you only want to show one entry per group, you can add a <div> element with ID matching cp-target-group-501 where 501 is the Buyer group ID. When a visitor calls the displayed number, they’ll be routed as normal to one of your grouped Buyers. This is useful when you have multiple Buyers for the same company, each with different hours of operation.

Like with our number display script, use replacement tokens [number] and [plain_number] within each cp-target div to insert the formatted phone number and unformatted phone digits of the trackable number.

We’ll only display the buyers that match your visitor, and that are open and able to receive a phone call.

You can put any content you want in the Buyer/target divs, like a logo, the name of the buyer, and a description. We’ll only display the Buyers that match and are open and able to receive a phone call. Set the divs as hidden by default to make sure they don’t “flash” while the display script is executing.

If you’re passing in arbitrary tags like zip-code tags, you’ll need to have a number pool configured for the campaign so that we can dynamically assign phone numbers for the visitor to call.

No matching Buyers

When there’s no Buyer that can serve the visitor, we enable the display of div with ID cp-targets-none. This div will be hidden if there are Buyers displayed.

jQuery integration

When we’re done processing the results and Buyers have been displayed, we fire event cp-results-processed on $(document).

Demo App
Our demonstration implementation, a lead-gen form for auto insurance.

View our demo app at This app features the option of choosing between click-to-call or Retreaver Results.

The code for this site is open source. Take it and use it in your own project.

Consumers enter their zip code and the results are automatically limited to the given geo. All calls are automatically tagged with whether or not the visitor already has insurance, and this information is passed to the Buyer via a whisper prompt.

The code for this site is freely available as a Ruby on Rails app, which can be easily adapted to suit your needs. Please fork the project and send us a pull request with your improvements. We’re looking forward to seeing your Results!

Collaborate With Us

April 28, 2014 | Jason Kay

With Retreaver you can share access to your account with your co-workers, publishers, and call buyers. Go to Settings>Users>Collaborators>+New Collaborator to create one from scratch, or just input an email when you create the Publisher or Buyer record.


Inviting a collaborator.

Add your Publishers as collaborators, and grant them access to a certain set of campaigns. They’ll then be able to create phone numbers, and view information about the calls they generate in their call log. You’ll be able to see what they’re up to in the new activity log on your dashboard.

Add your lead buyers as collaborators too, so they can monitor calls in real-time.


Add your co-workers as superusers and let them access your Retreaver account. Do not share logins.

Manage multiple companies

You’re now no longer limited to having only 1 company on your account. Perfect for agencies, power-users, or resellers, you can now easily create and manage multiple companies.

New dashboard

Your Retreaver dashboard now brings you more of the information you need to know, in one place, and at a glance. The widgets along the top will be customizable in an upcoming release.

Our new charts put the focus back where it should be: on tracking conversions and optimizing ROI.

The recent activity section will help you keep track of changes being made to your account by different collaborators.

Improved call log

Call Log
The new tag statistics chart.

We’ve added a dynamically updating chart to the call log. Click “Calls & Conversions” on your call log to reveal the chart.

The call log now allows you to filter calls by tag, and has an incredible chart which breaks down conversions and non-conversions per tag value.

The chart on the call log automatically updates as you change your filters or search term, and you can easily save the chart to an image file or PDF to share.

Next steps

Learn more about collaborating with Publishers and Call Buyers


Receiving Postback Data from Third Party Systems

January 1, 2014 | Jason Kay

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


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


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:[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.


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:[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.