Session Trackers

Session Trackers serve one number from a pool of tracking numbers to website visitors, allowing you to associate calls to individual visitors, the keywords they searched for before arriving via search engine, and their browsing history on your site.

At this time, only one Session Tracker per company is supported.

Contents

Listing All Session Trackers

Return a paginated list of all the Session Trackers for the given company.

API Endpoint

Method URL
GET /v1/companies/{company_id}/session_trackers.json

Request Parameters

Name Type Required? Description
per_page number optional How many trackers to return for this request (default 100, maximum 250).
Example: 25
page number optional Page number that should be returned for this request (the first page is 1).
Example: 3

Pagination is supported only for consistency. Since only one Session Tracker per company is currently supported, this endpoint will currently only return an array of one or zero objects.

Response Fields

Name Type Description
id number Unique identifier for this Tracker.
Example: 519217
name string Descriptive Name for this Tracker.
Example: “Keyword Pool”
tracking_numbers array List of tracking phone numbers for this Tracker.
Example: ["+15558675309", "+15551234567"]
company object Basic information on which company owns this Tracker.
Example: {"id": 21981, "name": "Bob's Auto Shop"}
sms_enabled boolean Whether or not this tracker will route text messages.
Example: false
recording_enabled boolean DEPRECATED: This field is now part of the call_flow object.
Whether or not this tracker records inbound calls.
Example: true
call_flow object An object describing how calls are routed for this Tracker. See Call Flow.
source string or object An object describing the source of the calls that this tracker will handle. See Session Tracker - Call Sources.
whisper_message string A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message.
Example: Call from Facebook.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
Example: “2011-07-05T19:06:10Z”
disabled_at string If the tracker has been disabled, this will be the date and time at which it was disabled (UTC, ISO 8601 format). If the tracker is still enabled, this value will be null.
Example: “2011-07-05T19:06:10Z”

Example

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v1/companies/579122/session_trackers.json
{
  "page": 1,
  "per_page": 100,
  "total_pages": 1,
  "total_records": 1,
  "session_trackers": [
    {
      "id": 316716820,
      "name": "Keyword Pool",
      "created_at": "2013-05-19T18:04:11Z",
      "disabled_at": null,
      "whisper_message": "Call from Keyword Pool",
      "company": {
        "id": 241369837,
        "name": "Bob's Auto Garage"
      },
      "tracking_numbers": [
        "+15557579183",
        "+15557817119",
        "+15555722044",
        "+15557583755",
        "+15559177890",
        "+15557550589",
        "+15557579545",
        "+15557932293"
      ],
      "call_flow": {
        "type": "basic",
        "destination_number": "+15558675309",
        "greeting_text": null,
        "greeting_recording_url": "https://example.com/recordings/greeting.mp3?1401993577"
      },
      source: {
        "bing": [ "paid", "organic" ],
        "google": [ "organic" ]
      }
    }
  ]
}

Retrieving a Single Session Tracker

Get detailed information about a single session tracker for a given company.

API Endpoint

Method URL
GET /v1/companies/{company_id}/session_trackers/{tracker_id}.json

Request Parameters

None.

Response Fields

Name Type Description
id number Unique identifier for this Tracker.
Example: 519217
name string Descriptive Name for this Tracker.
Example: “TV Advertisement”
tracking_numbers array List of tracking phone numbers for this Tracker.
Example: ["+15558675309"]
company object Basic information on which company owns this Tracker.
Example: {"id": 21981, "name": "Bob's Auto Shop"}
sms_enabled boolean Whether or not this tracker will route text messages.
Example: false
recording_enabled boolean DEPRECATED: This field is now part of the call_flow object.
Whether or not this tracker records inbound calls.
Example: true
call_flow object An object describing how calls are routed for this Tracker. See Call Flow.
source string or object An object describing the source of the calls that this tracker will handle. See Session Tracker - Call Sources.
call_alerts array List of users who will be notified when this tracker receives a call.
Example: [{ "first_name": "John", "last_name": "Robertson", id: "12", "email": "john@example.com"}]
sms_alerts array List of users who will be notified when this tracker receives a text message.
Example: [{ "first_name": "John", "last_name": "Robertson", id: "12", "email": "john@example.com"}]
whisper_message string A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message.
Example: Call from Facebook.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
Example: “2011-07-05T19:06:10Z”
disabled_at string If the tracker has been disabled, this will be the date and time at which it was disabled (UTC, ISO 8601 format). If the tracker is still enabled, this value will be null.
Example: “2011-07-05T19:06:10Z”

Example

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v1/companies/579122/session_trackers/16021421.json
{
  "id": 160214210,
  "name": "Keyword Pool,
  "created_at": "2013-05-19T17:52:12Z",
  "disabled_at": null,
  "tracking_numbers": [
    "+14044276267",
    "+14045551234",
    "+14045559823",
    "+14041234252"
  ],
  "sms_enabled": true,
  "recording_enabled": false,
  "whisper_message": "Call from Keyword Pool",
  "call_flow": {
    "type": "basic",
    "recording_enabled": false,
    "destination_number": "+14041234567",
    "greeting_text": null,
    "greeting_recording_url": null
  },
  "source": {
    "google": [ "paid", "organic" ],
    "bing": [ "local" ],
    "yahoo": [ "local", "organic" ]
  },
  "call_alerts": [
    {
      "id": 300390903,
      "first_name": "John",
      "last_name": "Robertson",
      "email": "john@example.com",
      "created_at": "2014-05-19T13:47:47-04:00",
      "role": "admin"
    },
    {
      "id": 5120817,
      "first_name": "Kelly",
      "last_name": "Johnson",
      "email": "kelly@example.com",
      "created_at": "2014-05-19T13:47:47-04:00",
      "role": "notification"
    }
  ],
  "sms_alerts": [
    {
      "id": 5120817,
      "first_name": "Kelly",
      "last_name": "Johnson",
      "email": "kelly@example.com",
      "created_at": "2014-05-19T13:47:47-04:00",
      "role": "notification"
    }
  ]
}

Creating a Session Tracker

Create a new session tracker for the given company.

API Endpoint

Method URL
POST /v1/companies/{company_id}/session_trackers.json

Request Data

Name Type Required? Description
call_flow object required An object describing what happens to the client’s call. See Call Flow.
pool_size number required How many phone numbers to allocate to this tracker. Must be betwen 8 and 50.
Example: 10
pool_numbers object required An object describing constraints for provisioning tracking phone numbers. See Creating a Number.
source string or object required An object describing which visitors will be served this tracker. See Session Tracker - Call Sources.
swap_target string optional The telephone number to target on your website. We will search for this number on your website and replace it with your tracking phone number. You do not need to format this number, we will look for all possible formats. If no swap target is provided, the destination number will be used.
Example: “7705551234”
whisper_message string optional A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message.
Example: Call from Facebook.

If the whisper message contains [source], it will whisper the name of the tracker.
Example: Call from [source] with a source named Keyword Pool will whisper Call from Keyword Pool.

Response Fields

Name Type Description
id number Unique identifier for this Tracker.
Example: 519217
name string Descriptive Name for this Tracker.
Example: “Keyword Pool”
tracking_numbers array List of tracking phone numbers for this Tracker.
Example: ["+15558675309", "+15551234567"]
company object Basic information on which company owns this Tracker.
Example: {"id": 21981, "name": "Bob's Auto Shop"}
sms_enabled boolean Whether or not this tracker will route text messages.
Example: false
recording_enabled boolean DEPRECATED: This field is now part of the call_flow object.
Whether or not this tracker records inbound calls.
Example: true
call_flow object An object describing how calls are routed for this Tracker. See Call Flow.
source string or object An object describing the source of the calls that this tracker will handle. See Session Tracker - Call Sources.
whisper_message string A ‘Whisper Message’ is a short message that plays to the call recipient before the call is connected. The caller does not hear this message.
Example: Call from Facebook.
created_at string The date and time the Tracker was created in UTC (ISO 8601 format).
Example: “2011-07-05T19:06:10Z”
disabled_at string If the tracker has been disabled, this will be the date and time at which it was disabled (UTC, ISO 8601 format). If the tracker is still enabled, this value will be null.
Example: “2011-07-05T19:06:10Z”

Example

echo '
{
  "call_flow": {
    "type": "basic",
    "recording_enabled": true,
    "destination_number": "+15553104554",
    "greeting_text": "This call will be recorded for quality assurance"
  },
  "pool_size": 10,
  "pool_numbers": {
    "area_code": "555",
    "local": "+15553104554"
  },
  "source": {
    "google": ["paid", "organic"],
    "bing": ["paid", "organic"],
    "yahoo": ["paid", "organic"]
  },
  "swap_target": "7705551234",
  "whisper_message": "Call from [source]"
}
' |
curl -H "Authorization: Token token=abc1234" \
     -H "Content-Type: application/json"     \
     -d @-                                   \
  https://api.callrail.com/v1/companies/12512/source_trackers.json
{
  "id": 127163,
  "name": "Keyword Pool",
  "created_at": "2014-03-20T15:42:00Z",
  "disabled_at": null,
  "sms_enabled": true,
  "recording_enabled": true,
  "whisper_message": "Call from [source]",
  "company": {
    "id": 12512,
    "name": "Ron's Surf Shop"
  },
  "call_flow": {
    "type": "basic",
    "recording_enabled": true,
    "destination_number": "+15553104554",
    "greeting_text": "This call will be recorded for quality assurance"
  },
  "source": {
    "google": ["paid", "organic"],
    "bing": ["paid", "organic"],
    "yahoo": ["paid", "organic"]
  },
  "tracking_numbers": [
    "+15554512710",
    "+15554512702",
    "+15554512730",
    "+15554512704",
    "+15554512750",
    "+15554512706",
    "+15554512770",
    "+15554512708",
    "+15554512790",
    "+15554512711"
  ]
}

Deleting a Session Tracker

Disabling a session tracker will permanently release its numbers. This action is immediate and cannot be undone.

API Endpoint

Method URL
DELETE /v1/companies/{company_id}/session_trackers/{tracker_id}.json

Request Parameters

None.

Response Fields

None. On success, response will be 204 NO CONTENT.

Example

curl -H "Authorization: Token token=abc1234" \
  -X DELETE \
  -v \
  https://api.callrail.com/v1/companies/291571/session_trackers/5.json
< HTTP/1.1 204 No Content
< Cache-Control: no-cache
< Connection: close
<
* Closing connection 0

Call Sources

The Call Source object describes the type of website visitor who will be tracked by this Session Tracker.

Tracking All Visitors

To track all website visitors regardless of source, specify the string "all" in place of the object. This is the most common usage scenario.

Track all website visitors, regardless of source:

"all"

Tracking Specific Search Visitors

Session Trackers can also be used to only track visitors from specific search engines. Session Trackers currently support Google, Yahoo, and Bing.

The format of the Sources object for a Session Tracker is as follows:

Name Type Description
google array An array of types of Google Search to be handled by this tracker. “paid”, “local”, and “organic” are valid.
bing array An array of types of Bing Search to be handled by this tracker. “paid”, “local”, and “organic” are valid.
yahoo array An array of types of Yahoo Search to be handled by this tracker. “paid”, “local”, and “organic” are valid.

Only serve the Session Tracker to Google Paid or Organic traffic:

{
   "google": ["paid", "organic"]
}

Serve the Session Tracker to Local or Organic traffic from all search engines:

{
   "google": ["local", "organic"],
   "yahoo": ["local", "organic"],
   "bing": ["local", "organic"]
}