Configuring the Retreaver Call Reservation API to ping Campaigns for Buyers

Call Reservation API

The Retreaver call reservation API offers campaign managers the ability to create an inhouse ping/post system capable of returning dynamic endpoints from their Retreaver campaigns to prospective call generators. This feature subsequently offers publishing partners the ability to ping Retreaver campaigns for a transfer number available to take their call.


 

Step 1) Enabling Call Reservation

Contact Retreaver support to enable the Call Reservation API for your listed company ID. We will enable and configure your account to support call reservation using your company ID. 

 

Step 2) Creating a Call Reservation Webhook

If you are the campaign manager looking to purchase calls from a publisher, head to the desired campaign that will be purchasing calls. Navigate to the bottom of the campaign overview page and create a new postback key using the "+" symbol:

Creating_Campaign_Call_Reservation_API_Link.png

 

Step 3) Configuring the Call Reservation Webhook

Configure the webhook to include any tags that you require the seller to provide in order to make a valid connection with your endpoints such as lead ids, name, age or state.

Retreaver requires that each call comes with an affiliate_id and caller_number parameter at the very minimum. They may also provide additional caller details by appending them to the end of the webhook similar to example below:

https://retreaverdata.com/call_reservations.json?key=ABCDEFG-123456&affiliate_id=[publisher_id]&caller_number=[caller_number]&caller_zip=[caller_zip]&caller_state=[caller_state]&first_name=[first_name]&last_name=[last_name]

When a publishing partner sends a POST request using the above call reservation webhook, Retreaver will assign an affiliate identifier to the provided caller id and return back a potential transfer number to your publishing partner for routing.

 

Step 4) Assigning a publisher to a Call Reservation Webhook

Create a new publisher profile for the selling party if it does not already exist and copy/paste the publisher_id into the webhook under the right hand side of the "affiliate_id=" parameter so that Retreaver can identify who sent in the call reservation request:

affiliate_id.png

Append the publisher id to the call reservation webhook like so:
https://retreaverdata.com/call_reservations.json?key=ABCDEFG-123456&affiliate_id=4321ABCD&caller_number=[caller_number]

Please ensure that your reporting and conversion logic matches this publisher profile moving forward. You will need to create a new conversion criteria on your campaign matching this publisher if it has not already been created in order to accredit this publisher for any converted calls that they have routed to your campaign.

 

Step 5) Posting Instructions for Publishers

Provide the created webhook link over to your call publishing partner, and instruct them to send a POST request to the provided webhook at the beginning of their engagement. If the posted Retreaver campaign contains a valid & available buyer at the time of the request, Retreaver will return a transfer number under a JSON response for them to route into.

Example Response Payload:

{
    "call_reservation": {
        "uuid": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
        "inbound_number": 11234567890,
        "caller_number": "+10987654321",
        "status": "no-target",
        "expires_at": null,
        "claimed_at": null,
        "wiped_at": null,
        "call": {
            "uuid": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
            "formatted_caller_number": "(098) 765-4321",
            "status": "no-target",
            "start_time": null,
            "end_time": 1000000000000,
            "caller_number": "+10987654321",
            "target_id": null,
            "winning_leg_connected_at": null,
            "winning_leg_disconnected_at": null
        },
        "matched_targets": [],
        "tag_values": [],
        "conversion_groups": []
    }
}


If your publishing partner generating calls is not a Retreaver user, they will then need to manually parse the "inbound_number" property to extract the desired transfer number.

Example JSON response parsing using JavaScript:
JSON.parse(Webhook_Response).call_reservation.inbound_number;

 

Step 6) Call Reservation Workflow Summary

If your publishing partner was provided an available inbound_number to route into, the following actions will take place:

  1. Retreaver will tag the caller id with an affiliate id and any other provided tags.
  2. The publisher will attempt to route the call to the inbound_number buyer on the campaign.
  3. Retreaver will convert the call based on the provided conversion criteria placed on the campaign.


7) Additional Step for Retreaver Publishers


7A) If the publishing partner is a Retreaver user, instruct them to create a new buyer using the [inbound_number] tag as the transfer number, it will be dynamically substituted as a response to a post attempt.

dynamic_buyer.png


The publisher will then need to place this newly created buyer on the campaign that they intend to sell calls from.

7B) They must also create a start ping webhook on the campaign intending to sell calls, this webhook will fire the call reservation webhook at the start of a call:

selling_party_webhook.png
Creating the start ping webhook that will ping the purchasing campaign for a dynamic endpoint at the start of a call.

 


 

Your publishing partner will now be able to request a transfer number from your campaign and directly route calls to an available buyer as well as receive attribution for any converted calls that they transfer over to you.

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.