PING/POST from Ringba to TrackDrive

(Using a Static Number on TrackDrive)

To do a PING/POST on Ringba, you will make use of Ring Tree Targets within a Ring Tree.  This document goes over how to set the Ring Tree Target to do the relevant PING followed by a POST.

What to ask for from your Targets as far as a number(s) needed:

One Number Use Cases:

• Static Payout to you from Target
• Variable Payout and/or Duration, but you will wait for a Postback On Conversions to get the Payout value.

Multiple Number Needed:

• If Dynamic Payout and/or Duration is needed Per Buyer on your Target's platform

NOTE:  Once you have made a RingTree Target for your TrackDrive Buyer, you can duplicate the Target and change just a few things:
Same URL: just fix the Number/SIP section to the right DID and the trackdrive_number in the PING webhook.
Different URL: In addition to the number change fix both the PING and POST URLs in the two webhook configs.

To access the Ringba menu item to maintain Ring Tree Targets, go to Ring Trees/Manage Ring Tree Targets.

While most of the logic on building out the Target is the same as a regular Target, the following will document the required options to work with the TrackDrive Incoming Webhooks:

Ensure the “Dynamic Number” value is “false”. (Note: in order to send calls to TrackDrive via SIP at the time this article was written, we can't get a SIP path to call from parsing, so you must use Static DIDs.

Ensure the “Confirmation Request” value is “true”.

NOTE: If you are using RTB and are not able to do the Confirmation Request,  you will receive warning notifications like pictured below:

TrackDrive designed our PING/POST for systems like ViciDial that could only do the PING manually from an agent action, but would not be able to parse the PING ID to send a POST.  If TrackDrive receives a call without a POST, the PING data will be inherited to make the lead, and the “try_all_buyers_ping_id” is assumed as the intended PING_ID to use.  You may safely use a Ring Tree Target with only a PING to TrackDrive if the number is already an RTB assigned number.

You may add a Trigger on the Campaign for After Connected to send data to TrackDrive for the second step.  It will not get data to the TrackDrive system in time to get to a buyer, but we will pick up data for the call during the call for things you need to send to update the call like the Ringba Call ID for postbacks.  However, since 2 step is not supported on RTB, the PING must have any data destined for the Buyer data post. 

Set the “Revenue Settings” based on the contract you have with your TrackDrive buyer:  

1. Static Revenue (NOTE: You can not select Static if you want to setup Postbacks, use Dynamic as the setting and set it that way so you can select the conversion type to be a Webhook Postback). 
    

2. Use the Payout Returned from TrackDrive (this does mean you can only check one buyer if you need to know what the Payout is going to be, since Ringba doesn't handle a multi buyer PING Response in the portal.
 

 3. If your TrackDrive Buyer is going to do a POSTBACK your Revenue, then Pick “Override” and then also Convert on Postback/Webook.
 

Set the “Request Settings” as follows:

o  URL: Supplied by Your TrackDrive Buyer. 
Example: https://subdomain.trackdrive.com/api/v1/inbound_webhooks/ping/medicare_buyer_availability_check 

o  HTTP Method: POST

o  Authentication: Leave Blank

o  Content Type: application/json

o  Body: (note,these are the minimum fields to send, but any of the fields that are in the Posting Instructions provided by the TrackDrive Buyer can also be added to the body. An Example of the PING/POST instructions can be found here.)
  {

 "trackdrive_number":"[REPLACE_WITH_ASSIGNED_BUYER_DID]",

 "traffic_source_id":"[REPLACE_WITH_ASSIGNED_TRAFFIC_SOURCE_ID]",

 "caller_id":"[tag:InboundNumber:NumberE164]",

"ringba_call_uuid" : "[Call:InboundCallID]"

}

Note: if this Ring Tree Target is part of an RTB number, the Call UUID here will be an RTB ID and not a Call ID, so you will have to use the method to get the “trackdrive_call_uuid” to TrackDrive on Target Connect in the Campaign since you will not be able to also do the POST (aka Step 2 of a Ring Tree Target).

Parse Special Values for “Use Ring Tree Settings”:

Note: In a recent release, new Targets can no longer pick the field name to parse to in the RESPONSE, but rather pick a field from the Response to use in the comparison to see if the REQUEST was accepted and where to find the bid price, etc.  If you can't get a successful Response from TrackDrive with your test data, if you add in “ping_test”:"true", or &ping_test=true if doing as a GET), you will always get a Successful Response and can see the fields you need to see on Success.

·        “Dynamic Bid Parsing” add a Parsing type of JPath and paste in the highlighted value buyers[0].offer_conversion_payout in the Parsing Expression and click Add Parsing Step.

“Call Acceptance Parsing” add a Parsing Type JavaScript and paste in the highlighted value (including the semicolon) return JSON.parse(input).status == "accepted"; and then Add Parsing Step.  This Javascript is checking to ensure we are returning “status”: “accepted” in the response.  If the PING wasn't accepted, then the Target will not be considered for the call.

“Dynamic Duration Parsing” add a Parsing type of JPath and paste in the highlighted value buyers[0].current_conversion_duration (default value) and then Add Parsing Step.   NOTE: Your TrackDrive client may be returning buyer[0].offer_conversion_duration if you are paid based on a static forwarded timer instead of basing it on the buyer timers, please check with your TrackDrive sales representative on which forwarded duration timer is being used in this configuration.

Set the “Confirmation Request Settings” as follows:

“Bid ID Parsing” 

• Pick JPath as the type of parse.  Since we are asking the Target for 1 number or many numbers depending on your payout agreement, the try_all_buyers_ping_id in the Parsing Expression and click Add Parsing Step.
   

“Confirmation Request” settings will be set as follows:

o  URL: Supplied by Your TrackDrive Buyer. 
Example: https://subdomain.trackdrive.com/api/v1/inbound_webhooks/post/medicare_buyer_availability_check

o  HTTP Method: POST

o  Authentication: Leave Blank

o  Content Type: application/json

o  Body: (NOTE: these are the minimum fields to send, but any of the fields you have data available that are in the Posting Instructions provided by the TrackDrive Buyer can also be added to the body)
{

            "traffic_source_id":"{ASSIGNED_TRAFFIC_SOURCE_ID}",

            "caller_id":"[tag:InboundNumber:NumberE164]",

            "ringba_call_uuid":"[Call:InboundCallId]",

            "ping_id":"[bid-id]"

}

At the time this article was written, Ringba does not have Parsing to get the Lead ID Generated on TrackDrive that we send in the POST RESPONSE.

The call is now ready to be transferred to the TrackDrive DID assigned to you by your buyer. 

POSTBACK: TrackDrive Buyer to Ringba Traffic Source

 

       

 

 

Postback Conversions from TrackDrive to Ringba

 

 

In Ringba - Create a Global Postback for Any Buyer

 

Ringba has a menu selection at Integrations/Webhooks that will be used to setup a Webhook for the Postback of converted calls.  It is easiest to set a Global Postback since the Call UUID is already unique; however, if you want to be more secure, you can set a Webhook for a single campaign or even for a single buyer to ensure the unique token for the Webhook is more secure.  

 

NOTE: A Global Webhook could be use for any Target to post back conversions, this logic is not just for the TrackDrive Integration.  In TrackDrive's opinion, you need only to setup one Webhook for Postbacks and it can be given to any Target to do a postback, since they would have to know both the UNIQUE Webhook token you see in the URL AND the exact call_uuid that you sent in a field to a buyer. 

 

From Integrations/Webhooks, click on Create Webhook.  Then simply fill in the following values:

NOTE: (even tho you can make custom field names for a webhook in Ringba, TrackDrive sets up a global hook on each client to get back to Ringba, and we are not expecting different field names than EXACTLY what you see below.  Our clients tag the number you are given with the ringba_webook_token and if the call also has ringba_call_uuid, the Global Postback Triggers.)

 

Name: Global Buyer Revenue Postback (or however you wish to name this webhook)

 

Call Token: call_id

 

Revenue Token: call_revenue

 

Fire Conversion: sale_successful=true

 

This will produce a URL with a unique identifier for the webhook in the URL.  You may simply give your TrackDrive Buyer the full URL produced from filling in the form as a Postback to place in TrackDrive.

 

Example URL: https://webhook.ringba.com/hook/WHbb01eb9114dc46429d7570fa4a6f87fb?call_id=[callUUID]&call_revenue=[conversionAmount]&sale_successful=true

 

Below is a picture of a Global Revenue Postback Webhook in Ringba:

 

 

In TrackDrive - Create a Global Ringba Postback Trigger

 

TrackDrive has a menu selection at Company/Webhooks where you can place a global trigger to Postback to any call that is from a Ringba Traffic Source and the ringba_call_uuid field has a value.  If you have not done so already, copy in the Global Trigger from TrackDrive Templates and then only a few things need to be changed.

 

From Company/Webhooks, click on the blue “New From Template” button to find available webhook templates and search for “Ringba”.  You will find a webhook to copy in called “GLOBAL TRIGGER: RINGBA WEBHOOK: Do a Postback for Ringba Traffic Sources if ringba_call_uuid is populated”.

 

Once the copy is done, you should not have to edit the Trigger or the Webhook URL in most situations.  However, it depends on if it is easier to map the “ringba_webhook_token” here (if the traffic source made a Global Webhook in Ringba, this would be the preferred place to identify this token value), or in each Number you assign to the Ringba Traffic Source (in the case they give unique webhook token values for each number you assign them).  You can combine both methods, it all depends on your Traffic Source's configuration in Ringba.

Option 1: Map “ringba_webhook_token” in the URL settings:

 

Edit the Webhook URL, then edit the “Ringba Webhook Token Field Mapping Group” using the inline menu. Click the “+ New Custom Field Mapping” button to add a New Custom Field Mapping. Then for any Ringba Traffic Source that uses global webhook for buyer revenue postback, set a filter for the traffic source and map the “ringba_webhook_token” to the unique value in the Ringba URL provided.

 

A picture of mapping the ringba_webhook_token in the Global URL Mappings is pictured below:

Option 2: Set the “ringba_webhook_token” in the Number provided to the Traffic Source:

 

If your Traffic Source didn't realize that Ringba can use a Global Webhook for Revenue Postback, it is highly suggested you guide them to this document on how to setup a Global Revenue Postback and use Option 1 above.  If they have a use case that they do need to give you many Webhook Tokens for various reasons, then is will be more logical to set the “ringba_webhook_token” value in the Number .

 

A picture of mapping the ringba_webhook_token in a TrackDrive Number is pictured below: