BASICS: PING/POST to TrackDrive
(aka: Incoming Webhooks)
Written by Rich Nolan
Updated at February 12th, 2024
PING/POST to TrackDrive
(known as Incoming Webhooks on TrackDrive Platform)
TrackDrive has implemented a state-of-the-art Incoming Webhooks technology that allows for your Traffic Sources to check for available TrackDrive Agents OR available Buyers before sending a call.
There are two different types of hooks with different responses:
- TD Agent Availability
- Buyer Availability
If you don’t have live agents on TrackDrive, only the Buyer Availability section of this document is relevant to you.
The TrackDrive Incoming Webhook for Buyer Availability is by far the most dynamic PING/POST technology available on the market. The design was made to minimize the amount of numbers used on the TrackDrive platform, with as little as one number per Traffic Source per Offer. NOTE: For the Static Number Forwarding Type, if the Traffic Source is not able to POST after they do a PING, but they send the CallerID on the PING, we will inherit the PING data as the POST data, and assume the “try_all_buyers_ping_id” should be processed for all the buyers that matched.
However, if your Traffic Source is unwilling to send the CallerID with the data, we also allow a Number Pool to be used so that Traffic Sources can control the flow of calls to buyers by the Number they forward the call to as opposed to being able to send a POST with the relevant PING_ID.
For more information about what type of Incoming Hook to send the Traffic Source AND whether they can use one number for all buyers or need one number per buyer, see this article.
The following sections document how to configure the Incoming Webhooks; as well as show how a Traffic Source would use them.
TrackDrive Internal Agent Availability Check
In the Offer/Edit scroll down to the section named “Incoming Webhooks” to maintain these records. You can either maintain Incoming Webhooks you have already made or add a new one. Click the “+ New Incoming Webhook” button to add a new webhook.
- Vanity ID: Instead of generating a UUID that is hard for traffic sources to remember, the API Key for an
Incoming Webhook is a free form ID. For this example, the Vanity ID is “medicare_td_agent_availability_check”. The Vanity ID is used in the URL of the incoming hook and should be named for what it is obviously used for.
- Webhook Type: For Incoming Webhooks that will be checking if a TrackDrive Instant Agent is available to take an inbound call, the type is “Check if an instant agent is available”.
- Name: This is the name of the Incoming Webhook (aka Friendly Name) used to show as the Title of the Hook when displayed on posting instructions.
- Description: This is a more elaborate description of what the incoming webhook is used for; however, many times the Name and Description will be the same by preference.
- Require Traffic Source ID: If you want the Traffic Source to include their traffic_source_id in the webhook payload, check the box (it makes most sense to require the traffic_source_id to be sent on all incoming webhooks).
- Require User Auth Token: For security reasons, you may wish to have the Traffic Source also include his TrackDrive API Authorization in order to be able to check for available agents. If you want to require this, the Traffic Source must be added as a Team, and given API Authorization to PING for available agents. Use the Integrations/API & Access Tokens menu option to get your team members Basic Authorization information.
- Search Criteria: Normally, the easiest way to check for available agents is to just pick the Call Flow that an incoming call would find your TrackDrive Instant Agents related to this Incoming Webhook (preferred method). However, you may also force the check to look only for Agents on Certain Agent Groups or individual agents.
EXAMPLE PING FOR AGENT:
Protocol:POST/GET
NOTE: Any additional data added after this will allow for more reliable matching. For example, adding &zip=80920&caller_id=7195220111 would allow for matching agents by geo and suppression checking. An example of how a PING check for a TrackDrive Agent to be available can be found here.
Agents ARE Available Response:
{
"errors":[],
"success":true,
"available_agent_count":1,
"available_agent_ids":[10143349]
}
Agents NOT Available Response:
{
"errors":["There are no available agents / buyers."],
"success":false,
"available_agents_count":0,
"available_agent_ids":[]
}
NOTE: The Agent PING is not a PING/POST, but rather a true check for agents, the data you send to check that all filters match an agent is not data used when the call is received. You can do a PING/POST to check for Buyers or a Direct Post to get the data for the call.
TrackDrive Buyer Availability Check
In the Offer/Edit scroll down to the section named “Incoming Webhooks” to maintain these records. You can either maintain Incoming Webhooks you have already made or add a new one. Click the “+ New Incoming Webhook” button to add a new webhook.
- Vanity ID: Instead of generating a UUID that is hard for traffic sources to remember, the API Key for an Incoming Webhook is a free form ID. For this example, the Vanity ID is “medicare_buyer_availability_check”. The Vanity ID is used in the URL of the incoming hook and should be named for what it is obviously used for.
- Webhook Type: For Incoming Webhooks that will be checking if a Buyer is available to take an inbound call, the type is “Check if a Buyer is available”.
- Name: This is the name of the Incoming Webhook (aka Friendly Name) used to show as the Title of the Hook when displayed on posting instructions.
- Description: This is a more elaborate description of what the incomingwebhook is used for; however, many times the Name and Description will be thesame by preference.
- Require Traffic Source ID: If you want the Traffic Source to include theirtraffic_source_id in the webhook payload, check the box.
- Require User Auth Token: For security reasons, you may wish to have the Traffic Source also include his TrackDrive API Authorization in order to be able to check for available agents. If you want to require this, the Traffic Source must be added as a Team, and given API Authorization to PING for available agents. Use the Integrations/API & Access Tokens menu option to get your team members Basic Authorization information.
- Process Ping/Post Buyers: If the buyers found on the call flow have Conversion Settings set to do a PING to the buyer to see if he can take a call, do you want to run those PINGs when the Incoming Webhook is received? If you do want to run those PINGs, check this box.
- Forwarding Number Type:
Static Number: If your Traffic Source can do both a PING and a POST, then select “Static Number” as your Traffic Source will be identifying via webhooks what we should do with the caller when the call is answered, based on the PING_ID.
Unique Phone Numbers: Many legacy type systems are not capable of Parsing the results of a PING to do a follow up POST. In this case, a Static Number can’t be used to forward calls from your Traffic Source, and a Number Pool will have to be configured for the offer to be used to Track Forwarding Number/Buyer combinations. TrackDrive will use the Number we receive the call on to determine which buyer would get the call. If you pick this type of Forwarding Number Type, you will be asked which Number Pool will be used for this option.
- Response Format:
PING/POST Attributes: You can configure what will be sent in the RESPONSE BODY of both the PING and the POST responses. All of the Buyer Attributes, Traffic Source Conversion Setting Attributes, and any Additional Tokens added on Buyer records can be sent in the responses.
The responses will have a “Try All Buyers” PING_ID and Forwarding Number so that your Traffic Source can just let the call route to any buyer that fits. However, the Responses will also have a Buyer Array with a PING_ID and Forwarding Number for each buyer in the case your Traffic Source would like to manage the individual buyer to take a call.
EXAMPLE PING FOR BUYER USING STATIC NUMBER:
NOTE: The PING will combine the Number’s Tokens added to a Number in TrackDrive, with the Tokens in the PING data. For example: the number may have “call_type=warm_transfer”, that will be added to the PING Data the Traffic Source sends to be included in buyer matching.
The more a PING has for data, the more likely it is that the POST will be accepted. However, if you leave off information on the PING (for example, caller_id or currently_insured=false) the POST may then disqualify some or all of the buyers that matched on the PING.
NOTE: A Traffic Source Number can be configured with a Buyer or Buyer Group on the Additional Tokens, which will then only allow those buyers to match.
NOTE: Some platforms can not do both a PING and a POST with the PING ID TrackDrive returns (for example ViciDial). If you are on a platform that can only PING to see if TrackDrive has buyers, you don't have to do the POST and TrackDrive will inherit the PING data and use the “try_all_buyers_ping_id” automatically when we see the Caller Number on the TrackDrive Number you used in the PING.
The below examples are live examples, you may click on the links and see a real time response:
Protocol: POST/GET (we accept any POST as POST Json Body as well)
Single Number Assigned to Traffic Source PING EXAMPLE (Traffic Source IS Sending Caller Number):
Example Responses from a Successful PING:
Dynamic Number Returned in PING RESPONSE PING EXAMPLE (TS IS NOT Sending Caller Number): https://ppc-logix.trackdrive.com/api/v1/inbound_webhooks/ping/medicare_buyer_availability_no_caller_number?traffic_source_id=9999&zip=80920&call_type=warm_transfer&ping_test=true
Example Responses from a Successful PING:
NOTE: The TrackDrive client may not require the Caller Number on a PING for the Static Number Method, but additional data added after this will allow for more reliable matching. For example, adding &zip=80920&caller_id=7195220111 would allow for matching buyers by geo and suppression checking. Sending other related contact fields that may be used in buyer filters can also help in matching (for example: &medicare_parts_a_&_b=true).
If your platform requires the Forwarding Number to be parsed even if Forwarding to a Static Number, PINGs do not have that available by default, but that can be configured on the TrackDrive Platform to accomodate that need, but it is not necesary to PING first.
For the Number Pool Type of Incoming Hook, a PING is not required and the POST endpoint can be used as the way to check for buyers AND post the lead data in one step.
Buyers NOT Available Response Example:
{
"success":false,
"status":"no_matching_buyer",
"errors":["There were no buyers listed on any call flow."],
"try_all_buyers_ping_id":null,
"try_all_buyers":{},
"ping_ids_expiry_in_seconds":9999,
"buyers":[],
"call_router_id":66453
}