Introduction

This API is currently under development.

The Retreaver Call Control API provides control over complex call flows using revocable API keys which are scoped by Contact Handler or Handler Group and action.

For instance, I can provide my call center with an API key which only allows them to reject calls that have been routed to them, but which doesn't allow them to perform any other actions or to modify calls routed to other Contact Handlers.

Version

This is version 1.0 of the Call Control API.

Multi-format

The Call Control API can be accessed by JSON or XML. Simply change the file extension and Content-Type header to match your preferences.

We recommend using JSON since XML is archaic, has high overhead, and is generally awful.

Format	Content-Type	Extension
JSON	application/json	json
XML	text/xml	xml

Paginated

Retreaver is a RESTful paginated API that returns 25 results per page. Each relevant index response will have a Link HTTP header present.

Link: <https://retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&sort_by=created_at&order=asc&page=6996>; rel="last", <https://retreaver.com/calls.json?api_key=woofwoofwoof&company_id=1&sort_by=created_at&order=asc&page=2>; rel="next"

By parsing the Link header, you can determine the last, next, and previous pages.

Nomenclature

Please note, this documentation uses our Enterprise Edition nomenclature.

Old	Performance Marketing Edition	Enterprise Edition
Affiliate	Publisher	Source
Target	Buyer	Contact Handler/Call Endpoint
Target Group	Buyer Group	Handler Group

How Calls Work

Legs of a Call

In-band Signals vs Out-of-band Signals

Authentication

To authorize, use this code:

# With cURL, you can just pass the correct API with each request.
curl "https://api.retreaver.com/call_control/v1/active_calls.json?api_key=woofwoofwoof"

Make sure to replace woofwoofwoof with your API key.

Retreaver uses API keys to allow access to the API. The Call Control api uses separate API keys depending on the action taken by your Contact Handler or Group.

Active Calls

The Active Call API allows the call handler to determine if a call that was routed to them was routed through Retreaver, and if so, to retrieve the Call's UUID and the caller's real CallerID.

The Active Calls API only returns calls that are in progress and which have a matching CallerID in either the caller_number or caller_number_sent fields, which have been routed to the Handler or Group matching the API key used.

List Active Calls

curl "https://api.retreaver.com/call_control/v1/active_calls.json?api_key=woofwoofwoof"

The above command returns JSON structured like this:

{
  "success": true,
  "results": [
    {
      "caller_number": "+18668987878",
      "caller_number_sent": "+18665551234",
      "dialed_out_number": "+14166686980",
      "call_uuid": "e64268f8-18a3-4881-b8ed-80e06b17fa74",
      "started_at": 1511218175475,
      "dialed_out_at": 1511218175475
    }
  ]
}

If one or more call is found, success is set to true. Results are returned in reverse-chronological order with the most recently dialed calls first.

HTTP Request

GET https://api.retreaver.com/call_control/v1/active_calls.json?api_key=woofwoofwoof

Request Parameters

Parameter	Description
api_key	An API Key belonging to a Contact Handler or Group.

Response Parameters

Parameter	Description
caller_number	The actual phone number of the caller, as received by Retreaver or as entered in by the transferring agent.
caller_number_sent	The CallerID used by Retreaver when sending the call to the Call Endpoint. This may be a randomized value if a Static Caller Number is detected.
dialed_out_number	This is the number of the Call Endpoint which we dialed.
call_uuid	This is the universally unique identifier used to access the call.
started_at	The time the call was received by Retreaver, in milliseconds since Unix epoch.
dialed_out_at	The time the call was dialed out to the Call Endpoint, in milliseconds since Unix epoch.

Call Transfer

The Call Transfer API provides the functionality needed to perform attended or unattended call transfers.

Transfer a Call

Using the Call UUID fetched via the Active Calls API above, the Call Endpoint can then transfer the call in either an attended or unattended fashion.

curl ""
curl -s \
    -X POST \
    https://api.retreaver.com/call_control/v1/calls/CALL_UUID/transfer.json?api_key=woofwoofwoof \
    -H "Content-Type: application/json" \
    -d '{"hold_caller":true,"transfer_to":"+18668987878"}'

The above command returns JSON structured like this on success:

{
  "success": true,
  "transfer_uuid": "d12c9c93-19eb-491d-9afa-e30cbb02e832"
}

or like this on failure:

{
  "success": false,
  "error": "call not live"
}

Request Parameters

Parameter	Description
api_key	An API Key belonging to a Contact Handler or Group.
hold_caller	When true, the caller is placed on hold and an unattended transfer is initiated. When not true, an attended transfer is initiated with all three parties conferenced at once.
transfer_to	The phone number or SIP address to transfer the call to.

Response Parameters

Parameter	Description
success	Whether the call transfer was successful or not.
transfer_uuid	The UUID of the transfer, which must be recorded to perform further actions against the transfer.
error	An error message.

Error Messages

Error	Meaning
call not live	The call has already terminated.
cannot dial transfer_to number	The number you are attempting to dial could not be dialed, most likely due to restrictions on your account.
call already transferred	A call transfer is already in progress on this call and it cannot be re-transferred using this API key. You must use the transfer key of whatever Endpoint the call was transferred to.
not authorized	The API key is invalid.

Connect the Caller (unattended transfer)

Once the call has been transferred with hold_caller "true", the caller can be bridged in to the conference by using the Transfer UUID.

curl -s \
 -X POST \
 https://api.retreaver.com/call_control/v1/transfers/7df81876-6e46-4b50-945e-7f5ad97a555e/conference_caller.json \
 -H "Content-Type: application/json"

The above command returns JSON structured like this on success:

{
  "success": true
}

or like this on failure:

{
  "success": false,
  "error": "call not live"
}

Request Parameters

Parameter	Description
transfer_uuid	The UUID of the transfer retrieved from the Transfer API above.

Response Parameters

Parameter	Description
success	Whether the request was successful or not.
error	An error message.

Error Messages

Error	Meaning
call not live	The call has already terminated.
caller hung up	The caller disconnected while on hold.
caller not held	The caller was not transferred using hold_caller "true" and can hear everything your agent is saying!
transfer not found	The transfer UUID is invalid.

Stop the Transfer

If the Call Endpoint that you attempted to transfer the call to doesn't pick up or can't take the call, you can terminate the outbound leg to the Endpoint using the method below.

curl -s \
 -X DELETE \
 https://api.retreaver.com/call_control/v1/transfers/7df81876-6e46-4b50-945e-7f5ad97a555e.json \
 -H "Content-Type: application/json"

The above command returns JSON structured like this on success:

{
  "success": true
}

or like this on failure:

{
  "success": false,
  "error": "call not live"
}

Request Parameters

Parameter	Description
transfer_uuid	The UUID of the transfer retrieved from the Transfer API above.

Response Parameters

Parameter	Description
success	Whether the request was successful or not.
error	An error message.

Error Messages

Error	Meaning
call not live	The call has already terminated.
transfer not in progress	The outbound leg going to the transferee has already terminated.
transferor not present	The agent who originally accepted the call is no longer on the call. We will not terminate the call in this case because it would leave the caller with dead air.
transfer not found	The transfer UUID is invalid.

HTTP Request

DELETE https://api.retreaver.com/call_control/v1/transfers/7df81876-6e46-4b50-945e-7f5ad97a555e.json

Live Call Return

Allows the transferee to "return" a call that has been transferred to them, even though they have already picked up the call. This allows call centers to pick up a call and play on-hold messages or ringing while they queue the caller.

Once they execute a call return, the call is "taken back" by Retreaver and the next Contact Handler is determined and dialed.

Live Call Return API keys are associated with a Contact Handler or Group and a timeout given in seconds. Once a call is transferred to a Handler, the timer starts, and after the timeout duration has passed the call can no longer be returned.

Return a Call

Live Call Acceptance

Allows the transferee to "accept" a call that has been transferred to them, preventing the system from "taking back" a call that has already been connected to them.

In a way the Live Call Acceptance API is the opposite of the Live Call Return API. With the Call Return API, Retreaver assumes a call is accepted by the Handler as soon as it is picked up. With the Call Acceptance API, Retreaver assumes the call is not accepted until the acceptance endpoint is requested.

Which paradigm is used depends on the settings of the individual Call Handler.

Accept a Call

Errors

The Retreaver Core API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request was unintelligible. Check your formatting.
401	Unauthorized -- Your API key is wrong or missing.
403	Forbidden -- You didn't pass in your Company ID or you're using the wrong API key.
404	Not Found -- It actually, really doesn't exist.
405	Method Not Allowed -- It doesn't respond to the HTTP action you used.
406	Not Acceptable -- You requested a format that isn't JSON, or, sigh, XML.
410	Gone -- It up and left or was otherwise deleted.
418	I'm a little teapot!
429	Too Many Requests -- Slow down. Highly concurrent requests are frowned upon.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.