Call Tracking Metrics - Calls

📖 Overview

Call tracking module provides comprehensive call analytics including call lists, summary statistics, and timeline data for visualization. Supports advanced filtering, pagination, and call status tracking.

Source Files:

• Controller: external/Integrations/CallTrackingMetrics/Controllers/calls.js
• Provider: external/Integrations/CallTrackingMetrics/Providers/calls-api.js
• Routes: external/Integrations/CallTrackingMetrics/Routes/calls.js

External APIs:

• POST /api/v1/accounts/:id/calls/search.json - Call search
• GET /api/v1/accounts/:id/reports/series.json - Analytics

🔧 Key Functions

getCallsList(req, res, next)

Purpose: Retrieve paginated call list with filtering

Endpoint: GET /v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/calls

Parameters:

• page (Number) - Page number
• limit (Number) - Results per page
• start_date (String) - Filter start date
• end_date (String) - Filter end date
• call_status (Array) - Filter by status (answered, failed, no-answer, canceled)
• sort (String) - Sort field (name, date, duration)
• order (String) - Sort direction (asc, desc)

Default Filters Applied:

{
  multi_sources_operator: 'includes',
  reported: 1,
  with_time: 1,
  excluded: 0,
  converted: 0,
  form_entries: 0,
  filter_visitor_data: 0,
  has_audio: 0,
  stats: 'off',
  call_score_min: 0,
  call_score_max: 5,
  exclude_fields: 'transcription_text,chat_messages'
}

Returns: Paginated call list

{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "id": "call_123",
      "caller": "+15551234567",
      "tracking_number": "+15559876543",
      "duration": 180,
      "call_status": "answered",
      "start_time": "2023-10-01T14:30:00Z",
      "source": "google",
      "recording_url": "https://..."
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 10,
    "total_items": 95
  }
}

getCallsSummary(req, res, next)

Purpose: Get aggregated call statistics

Endpoint: GET /v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/calls/summary

Parameters:

• start_date (String) - Summary start date
• end_date (String) - Summary end date
• interval (String) - Grouping interval (day, week, month)
• call_status (Array, optional) - Filter by status

Business Logic:

• If no call_status provided, fetches three separate reports:
  1. All calls
  2. Answered calls only (status: answered)
  3. Missed calls only (status: failed, no-answer, canceled)
• Merges results to include total_answered_calls and total_missed_calls metrics

Returns: Summary analytics

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "aggregations": {
      "total": { "value": 245, "percent": "100" },
      "total_answered_calls": { "value": 233, "percent": "95.1" },
      "total_missed_calls": { "value": 12, "percent": "4.9" },
      "total_duration": { "value": 41940, "percent": "100" },
      "average_duration": { "value": 180 }
    },
    "groups": {
      "items": [
        {
          "key": "2023-10-01",
          "metrics": {
            "total": { "value": 12, "percent": "4.9" },
            "total_answered_calls": { "value": 11, "percent": "4.5" },
            "total_missed_calls": { "value": 1, "percent": "0.4" }
          }
        }
      ]
    }
  }
}

getCallsByTimeline(req, res, next)

Purpose: Get time-series call data for charts

Endpoint: GET /v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/calls/chart

Parameters:

• start_date (String) - Chart start date
• end_date (String) - Chart end date
• by (String) - Group by field (default: direction)

Returns: Time-series data

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "series": [
      {
        "name": "inbound",
        "data": [
          { "x": "2023-10-01", "y": 12 },
          { "x": "2023-10-02", "y": 15 }
        ]
      }
    ]
  }
}

📊 Call Status Values

Status	Description
answered	Call was answered
failed	Call failed to connect
no-answer	Call rang but not answered
canceled	Call was canceled before answer

⚠️ Important Notes

• 📞 Call Search: Uses POST method for advanced filtering
• 📊 Summary Reports: Automatically splits answered vs missed calls
• 📈 Timeline Data: Returns series format for chart visualization
• 🔍 Field Selection: Excludes transcription and chat by default
• 🔐 Authentication: Uses Basic Auth headers from stored credentials
• ⏱️ Intervals: Supports day, week, month grouping for summaries

---

🔗 Related Documentation

• Integration Overview: Call Tracking Metrics
• Authentication: Credential Management
• Trackers: Tracking Number Management