Developer API: /widgets/data

Last updated at

Widgets data endpoint allows you to pull pre-calculated data, in a manner that gives you the ability to display it using the Freespee widgets library or any other charts library of your choice.

 

GET

Mandatory parameters

Name Type Possible types:
type string

Multiple values:
call_length_distribution
calls_per_day
calls_top_attributions
daily_call_distribution
geographic_origin
top_customers_by_calls

Single values:
average_calls_per_user
call_durations
call_totals
missed_calls
unique_callers 

Optional parameters

Name Type Description
customer_id int Freespee’s unique id for the customer, can be retrieved using the /customers endpoint
from_date string Date must be in format: YYYY-MM-DD
to_date string Date must be in format: YYYY-MM-DD

Output

Widget types and responses

 

There are 2 types of widgets, single value and multiple value widgets. The choice on how to display the value can be entirely up to you.

 

The response will always be a JSON with the dataset property set to the type of the data, and the datasources property containing the data in the data field.

missed_calls - total amount of missed calls for selected period (single value)
{
   "dataset": "missed_calls",
   "datasources": [
      {
           "datasource": 0,
           "data": "74"
      }
  ]
}
call_durations - average call duration for the selected period (single value)
{
   "dataset": "call_durations",
   "datasources": [
      {
           "datasource": 0,
           "data": 50
      }
  ]
}
average_calls_per_user - average calls per caller for the selected period (single value)
{
   "dataset": "average_calls_per_user",
   "datasources": [
      {
           "datasource": 0,
           "data": "1.0"
      }
  ]
}
call_totals - total calls for the selected period (single value)
{
   "dataset": "call_totals",
   "datasources": [
      {
           "datasource": 0,
           "data": "96"
      }
  ]
}
calls_top_attributions - top 5 call attributions for the selected period (multiple value -> user level tracking)
{
   "dataset": "calls_top_attributions",
   "datasources": [
      {
           "datasource": 0,
           "data": [
              {
                   "name": "Direct",
                   "val": "34"
              },
              {
                   "name": "Google SEO",
                   "val": "28"
              },
              {
                   "name": "Referrer/localhost",
                   "val": "8"
              }
          ]
      }
  ]
}
unique_callers - total unique callers for the selected period (single value)
{
   "dataset": "unique_callers",
   "datasources": [
      {
           "datasource": 0,
           "data": 24
      }
  ]
}
call_length_distribution - call length distribution for the selected period (multiple values)
{
   "dataset": "call_length_distribution",
   "datasources": [
      {
           "datasource": 0,
           "data": [
              {
                   "name": "missed",
                   "val": "74",
                   "isWarningValue": true
              },
              {
                   "name": "< 30 s",
                   "val": "7"
              },
              {
                   "name": "30 - 60 s",
                   "val": "9"
              },
              {
                   "name": "1 - 2 min",
                   "val": "6"
              }
          ]
      }
  ]
}
geographic_origin - calls per geographic origin based on the caller ID for selected period (multiple value)
{
   "dataset": "geographic_origin",
   "datasources": [
      {
           "datasource": 0,
           "data": [
              {
                   "name": "Charfield",
                   "val": 34
              },
              {
                   "name": "Mobile",
                   "val": 27
              },
              {
                   "name": "Chelsea",
                   "val": 17
              }
          ]
      }
  ]
}
daily_call_distribution - hourly call distribution for the selected period (multiple value) 
{
   "dataset": "daily_call_distribution",
   "datasources": [
      {
           "datasource": 0,
           "data": [
              {
                   "name": "00:00",
                   "Answered": 0,
                   "Missed": 0
              },
              {
                   "name": "01:00",
                   "Answered": 0,
                   "Missed": 0
              },

               . . .

              {
                   "name": "23:00",
                   "Answered": 0,
                   "Missed": 0
              }
          ]
      }
  ]
}
top_customers_by_calls - calls per accounts if customer_id is omitted (multiple value); same as call_totals if customer_id is added (single value)
{
   "dataset": "top_customers_by_calls",
   "datasources": [
      {
           "datasource": 0,
           "data": [
              {
                   "scId": "123456",
                   "name": "Customer 1",
                   "val": "507",
                   "url": "/mypages/dashboard/scid:123456"
              },
              {
                   "scId": "123457",
                   "name": "Customer 2",
                   "val": "139",
                   "url": "/mypages/dashboard/scid:123457"
              }
          ]
      }
  ]
}
calls_per_day - calls per day for the selected period (multiple value)
{
   "dataset": "calls_per_day",
   "datasources": [
      {
           "datasource": 0,
           "data": [
              {
                   "name": "2021-03-15",
                   "Answered": 0,
                   "Missed": 0
              },
              {
                   "name": "2021-03-16",
                   "Answered": 0,
                   "Missed": 0
              },
              {
                   "name": "2021-03-17",
                   "Answered": 6,
                   "Missed": 14
              },
              {
                   "name": "2021-03-18",
                   "Answered": 1,
                   "Missed": 11
              },
              {
                   "name": "2021-03-19",
                   "Answered": 0,
                   "Missed": 3
              }
          ]
      }
  ]
}