Call Tracking Metrics Integration

📖 Overview

Call Tracking Metrics (CTM) integration provides call tracking analytics, phone number management, and webhook-based event handling for DashClicks campaigns. Unlike CallRail, CTM uses Basic Authentication (username/password) instead of API keys.

Key Features:

• Username/password authentication with automatic invalidation detection
• Account and sub-account hierarchy management
• Call tracking with detailed metrics and summaries
• Tracking number (tracker) management
• Webhook support for real-time call events
• Campaign preservation logic on disconnection

API Base URL: https://api.calltrackingmetrics.com/api/v1

Authentication Method: Basic Auth (username + password)

🏗️ Architecture

Directory Structure

external/Integrations/CallTrackingMetrics/
├── Controllers/
│   ├── auth.js           # Authentication and credential management
│   ├── accounts.js       # Account listing
│   ├── calls.js          # Call tracking and analytics
│   ├── trackers.js       # Tracking number management
│   └── webhooks.js       # Webhook configuration
├── Providers/
│   ├── auth-api.js       # Authentication API calls
│   ├── account-api.js    # Account API calls
│   ├── calls-api.js      # Calls API calls
│   ├── trackers-api.js   # Tracker API calls
│   ├── call-webhook.js   # Webhook processing
│   └── get-headers.js    # Auth header builder
├── Models/
│   └── keys.js           # Credential storage model
├── Routes/
│   ├── auth.js           # Auth routes
│   ├── accounts.js       # Account routes
│   ├── calls.js          # Call routes
│   ├── trackers.js       # Tracker routes
│   └── webhooks.js       # Webhook routes
└── index.js              # Main router with error handling

Request Flow

sequenceDiagram
    participant Client as DashClicks Frontend
    participant Router as CTM Router
    participant Controller as Controller
    participant Provider as API Provider
    participant CTM as Call Tracking Metrics API
    participant MongoDB as MongoDB

    Client->>Router: Request with JWT
    Router->>Router: Verify authorization
    Router->>Router: Set IDs (tokenId, accountId)
    Router->>Controller: Route to controller
    Controller->>MongoDB: Retrieve credentials
    MongoDB-->>Controller: username, password
    Controller->>Provider: API call with Basic Auth
    Provider->>CTM: HTTP request
    CTM-->>Provider: API response
    Provider-->>Controller: Formatted data
    Controller-->>Client: JSON response

🗄️ MongoDB Collections

integrations.calltrackingmetrics.key

Purpose: Store CTM authentication credentials

Model: shared/models/calltrackingmetrics-key.js

Document Structure:

{
  "_id": ObjectId("507f1f77bcf86cd799439011"),
  "account_id": ObjectId("507f1f77bcf86cd799439012"),
  "user": "ctm_username",
  "password": "encrypted_password",
  "access_key": "ctm_api_access_key",
  "secret": "ctm_api_secret",
  "token_invalidated": false,
  "deleted": ISODate("2023-10-01T12:00:00Z"),  // Soft delete
  "createdAt": ISODate("2023-09-15T10:00:00Z"),
  "updatedAt": ISODate("2023-10-01T12:00:00Z")
}

analytics.calltrackingmetrics.userconfig

Purpose: Link CTM account to DashClicks account for campaign tracking

Model: shared/models/analytics-calltrackingmetrics-userconfig.js

Document Structure:

{
  "_id": ObjectId,
  "account_id": ObjectId,
  "token": "507f1f77bcf86cd799439011",  // Reference to key document ID
  "calltracking_account_id": "act_123456",
  "calltracking_sub_account_id": "sub_789",  // Optional sub-account
  "createdAt": ISODate,
  "updatedAt": ISODate
}

🔐 Authentication

Basic Authentication

CTM uses username and password authentication (not API keys):

Authentication Endpoint: POST /api/v1/authentication

Request Body:

user={username}
password={password}

Response:

{
  "access_key": "ctm_access_key_123",
  "secret": "ctm_secret_456"
}

Subsequent API Calls: All API requests use Basic Auth header:

Authorization: Basic {base64(access_key:secret)}

Token Invalidation Detection

Middleware: index.js error handler

Trigger: 401 Unauthorized response from CTM API

Actions:

1. Set token_invalidated: true on all keys for account
2. Return TOKEN_INVALIDATED error to client
3. User must re-authenticate with new credentials

🔄 Call Tracking Metrics Hierarchy

graph TD
    A[Account] --> B[Sub-Account Optional]
    A --> C[Tracking Numbers]
    B --> C
    C --> D[Calls]
    D --> E[Call Recordings]
    D --> F[Call Metrics]

Hierarchy Components

1. Account: Top-level organization (agency or business)
2. Sub-Account: Optional child account for client segmentation
3. Tracking Numbers: Phone numbers that track incoming calls
4. Calls: Individual call records with attribution data
5. Call Metrics: Aggregated analytics and reporting

📡 API Endpoints

Authentication Endpoints

Method	Endpoint	Description
POST	/v1/e/calltrackingmetrics/auth	Save credentials
POST	/v1/e/calltrackingmetrics/auth/config	Save user analytics config
DELETE	/v1/e/calltrackingmetrics/auth	Delete credentials

Account Endpoints

Method	Endpoint	Description
GET	/v1/e/calltrackingmetrics/:tokenId/accounts	List accounts
GET	/v1/e/calltrackingmetrics/:tokenId/accounts/:id	Get account details

Call Endpoints

Method	Endpoint	Description
GET	/v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/calls	List calls
GET	/v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/calls/summary	Get call summary
GET	/v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/calls/chart	Get timeline chart data

Tracker Endpoints

Method	Endpoint	Description
GET	/v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/trackers	List trackers
GET	/v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/trackers/:id	Get tracker details
POST	/v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/trackers	Create tracker
PUT	/v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/trackers/:id	Update tracker
DELETE	/v1/e/calltrackingmetrics/:tokenId/accounts/:accountId/trackers/:id	Delete tracker

Webhook Endpoints

Method	Endpoint	Description
POST	/v1/e/calltrackingmetrics/:tokenId/webhook	Create webhook
POST	/v1/e/calltrackingmetrics/webhook/call-update	Receive call update webhook (public)

🔧 Key Features

1. Credential Management

• Username/password authentication
• Automatic token invalidation detection on 401 errors
• Soft delete with campaign preservation
• Notification system (FCM + Email)

2. Account Management

• List all accounts with pagination
• Get individual account details
• Support for sub-accounts

3. Call Tracking

• Paginated call listing with filters
• Call summary analytics (answered, missed, duration)
• Timeline chart data for visualization
• Call status tracking (answered, failed, no-answer, canceled)

4. Tracking Numbers

• Create and manage tracking numbers
• Update tracker configuration
• Delete trackers
• List all trackers with pagination

5. Webhook Integration

• Real-time call event notifications
• Webhook creation and management
• Call update event processing

🔀 Integration with DashClicks

Campaign Tracking

User Config: Links CTM account to DashClicks campaigns

{
  "account_id": ObjectId,
  "calltracking_account_id": "act_123456",
  "calltracking_sub_account_id": "sub_789"  // Optional
}

Campaign Preservation

When deleting credentials:

• Global Delete (?global=true): Disable all campaigns, delete config and credentials
• Conditional Delete: Preserve credentials if active campaigns exist, only delete config

Notification System

FCM Notifications:

• Integration added: project_added type
• Integration disconnected: integration_disconnected type

Email Notifications:

• Send to account owner
• Send to parent account if sub-account
• Configurable via user preferences

⚠️ Important Differences from CallRail

Feature	CallRail	Call Tracking Metrics
Authentication	API Key (Bearer token)	Username/Password (Basic Auth)
API Token Format	Static API key	access_key + secret from login
Hierarchy	Account → Company → Tracker	Account → Sub-Account → Tracker
Sub-Account Support	No	Yes (optional)
Header Format	Token token={key}	Basic {base64(key:secret)}
Token Refresh	N/A (static key)	Re-authenticate on 401

🧪 Error Handling

Automatic Token Invalidation

Trigger: 401 Unauthorized from CTM API

Response:

{
  "success": false,
  "errno": 401,
  "message": "TOKEN_INVALIDATED",
  "code": "TOKEN_INVALIDATED"
}

System Actions:

1. Mark all account keys as token_invalidated: true
2. User must re-authenticate with new credentials
3. Frontend redirected to authentication page

Campaign Preservation

Issue: Deleting credentials while campaigns active

Solution:

• Check for active campaigns before deletion
• If campaigns exist, only delete user config
• Keep credentials intact for campaign tracking
• Use ?global=true to force complete removal

📝 Quick Start

1. Save Credentials

POST /v1/e/calltrackingmetrics/auth
{
  "username": "ctm_user",
  "password": "ctm_pass"
}

2. Configure Analytics

POST /v1/e/calltrackingmetrics/auth/config
{
  "token": "507f1f77bcf86cd799439011",
  "account_id": "act_123456",
  "subaccount_id": "sub_789"  // Optional
}

3. List Calls

GET /v1/e/calltrackingmetrics/{tokenId}/accounts/{accountId}/calls?page=1&limit=20

🔗 Related Documentation

• Authentication: Credential Management
• Accounts: Account Management
• Calls: Call Tracking & Analytics
• Trackers: Tracking Number Management
• Webhooks: Webhook Configuration
• CTM API: Call Tracking Metrics API Documentation

⚠️ Important Notes

• 🔐 Basic Auth: Uses username/password, not API keys
• 🔄 Token Refresh: Must re-authenticate on 401 errors
• 📊 Sub-Accounts: Optional sub-account support for client segmentation
• 🗑️ Soft Delete: Credentials marked as deleted, not removed
• 📞 Campaign Preservation: Keeps credentials if active campaigns exist
• 🔔 Notifications: Email and FCM notifications on connect/disconnect
• 👥 Parent Account: Sub-accounts send notifications to parent
• ⚠️ Global Delete: Use ?global=true query param for complete removal