Customer Codes Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Usage Flow
Import/Export Feature
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Customer Codes?

Customer Codes are billing/tracking identifiers that can be associated with calls. When a user enters a customer code before making a call, the code is recorded in the CDR (Call Detail Record) for billing, reporting, and cost allocation purposes.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                Customer Code System                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  User dials *78 (Customer Code feature)                         │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Code Entry                                  │   │
│  │  Play: "Enter your customer code"                        │   │
│  │  User enters: 12345#                                     │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Validation                                  │   │
│  │  SELECT code FROM public.customer_codes                  │   │
│  │  WHERE code = '12345' AND active = TRUE                  │   │
│  │                                                          │   │
│  │  ├─ Found → Store in channel variable                   │   │
│  │  └─ Not found → Continue (or reject based on config)    │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Set channel variable: customer_code = "12345"                  │
│  Return dial tone for outbound call                             │
│       │                                                         │
│       ▼                                                         │
│  CDR includes customer_code for billing/reporting               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.customer_codes`	Code definitions
CDR tables	Store code with call records

Key Files

File	Description
`admin/apps/web/src/modules/customerCodes/`	Frontend module
`admin/apps/web/src/i18n/en/customerCodes.json`	Translations

---

2. Module Overview (Commercial/Business)

Business Value

Customer Codes enable cost allocation and billing tracking:

Without Customer Codes	With Customer Codes
All calls billed to department	Bill to specific clients/projects
No project tracking	Track calls by matter/case
Manual cost allocation	Automated reporting
No accountability	Per-client billing

Use Cases

Law Firms / Professional Services

- Associate calls with client matters

- Bill phone time to specific cases

Agencies / Consultants

- Track calls by project

- Client-specific billing

Cost Centers

- Allocate telecom costs to departments

- Project-based accounting

Sales Teams

- Track calls by opportunity

- Campaign attribution

Feature Highlights

Feature	Benefit
CDR Integration	Codes appear in call records
Import/Export	Bulk management via CSV
Active Toggle	Enable/disable without deletion
Multi-tenant	Separate codes per domain
Description Field	Associate meaning with codes

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create customer codes for billing purposes
Add descriptions for code identification
Import/export codes via CSV
Enable/disable codes

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating a Customer Code                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: Code Information                                       │
│  ├─ Customer Code: ACME-001                                    │
│  ├─ Description: "ACME Corp - Main Account"                    │
│  └─ Active: ✓                                                  │
│                                                                 │
│  Step 2: Save                                                   │
│                                                                 │
│  Result: Code available for users to enter before calls        │
│          CDR will include "ACME-001" for billing               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

User Workflow (Using Customer Code)

Plaintext

1. User dials *78 (Customer Code feature)
2. System: "Enter your customer code"
3. User enters: ACME-001#
4. System: "Code accepted"
5. User dials destination number
6. Call proceeds normally
7. CDR records customer_code = "ACME-001"

Quick Tips

TIP

Meaningful Codes: Use codes that map to your billing system (e.g., client IDs, matter numbers).

TIP

Descriptions: Add clear descriptions for code lookup.

---

4. Configuration Fields Reference

Customer Code Fields

Field	Description	Example	Required
Customer Code	The code identifier	`ACME-001`	Yes
Description	Purpose notes	`ACME Corp Account`	No
Active	Code enabled status	On/Off	Yes

Code Format

Customer codes can include:

Alphanumeric characters (A-Z, 0-9)
Hyphens and underscores
Typically 4-20 characters

---

5. Usage Flow

Customer Code Entry Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                Customer Code Flow                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User dials *78 (or configured feature code)                 │
│     │                                                           │
│     ▼                                                           │
│  2. Prompt for customer code                                    │
│     │                                                           │
│     ▼                                                           │
│  3. User enters code (e.g., ACME-001#)                          │
│     │                                                           │
│     ▼                                                           │
│  4. Validate code (if validation enabled)                       │
│     ├─ Valid → Continue                                        │
│     └─ Invalid → Error or continue (based on config)           │
│     │                                                           │
│     ▼                                                           │
│  5. Store code in channel variable                              │
│     session:setVariable("customer_code", "ACME-001")           │
│     │                                                           │
│     ▼                                                           │
│  6. User dials destination                                      │
│     │                                                           │
│     ▼                                                           │
│  7. CDR includes customer_code field                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

CDR Integration

When a call with a customer code is completed:

customer_code field in CDR contains the entered code
Reports can filter/group by customer code
Billing systems can use code for allocation

---

6. Import/Export Feature

CSV Export

Purpose: Backup codes or migrate to another system. Format:

Csv

code,description,active
ACME-001,ACME Corp Main Account,true
BETA-002,Beta Inc Project Alpha,true
GAMMA-003,Gamma LLC Consulting,false

CSV Import

Import Modes:

Mode	Behavior
Skip existing	Keep current codes, skip duplicates
Update existing	Update description/active if code exists
Replace all	Delete all and import fresh

Required Columns:

code - The customer code
description - Optional notes
active - true/false

---

7. Common Scenarios & Examples

Scenario 1: Law Firm Client Matters

Codes:

Code	Description
SMITH-2024-001	Smith v. Jones Litigation
ACME-CORP-GEN	ACME Corp General Counsel
DOE-ESTATE-01	Doe Estate Planning

Usage: Attorneys enter matter code before client calls for billing.

Scenario 2: Consulting Project Tracking

Codes:

Code	Description
PROJ-ALPHA	Project Alpha - Deployment
PROJ-BETA	Project Beta - Assessment
INT-OVERHEAD	Internal / Non-billable

Usage: Consultants tag calls to projects for time tracking.

Scenario 3: Sales Campaign Attribution

Codes:

Code	Description
CAMP-Q1-WEB	Q1 Web Campaign Leads
CAMP-Q1-EMAIL	Q1 Email Campaign Leads
DIRECT-INBOUND	Direct Inbound Inquiries

Usage: Sales reps tag calls by lead source for ROI analysis.

---

8. Limitations & Important Notes

Technical Limitations

WARNING

Pre-Call Entry: Customer codes must be entered before the call, not during.

WARNING

Single Code: Only one customer code per call.

Best Practices

Consistent Format: Use standardized code formats
Meaningful Codes: Map to billing/CRM systems
Regular Audits: Archive unused codes
User Training: Ensure users know when to enter codes

---

9. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Code not in CDR	Code not entered/validated	Check call flow
"Invalid code"	Code not found/disabled	Verify code exists and is active
Users skip codes	Feature not enforced	Consider mandatory code policy

Diagnostic SQL

List customer codes:

Sql

SELECT code, description, active, created_at
FROM public.customer_codes
WHERE domain_id = [domain_id]
ORDER BY code;

Check code usage in CDR:

Sql

SELECT customer_code, COUNT(*) as call_count
FROM public.cdr
WHERE domain_id = [domain_id]
  AND customer_code IS NOT NULL
GROUP BY customer_code
ORDER BY call_count DESC;

---

10. Glossary

Term	Definition
Customer Code	Billing/tracking identifier for calls
CDR	Call Detail Record—contains call metadata
Matter Code	Legal industry term for client/case code
Account Code	Alternate term for customer code
Cost Center	Department/unit for expense allocation

---

Lua Handler Status

⚡ No Dedicated Handler Required

Customer Codes is primarily a configuration module. The code entry and validation is handled by the dialplan/feature code system, and the code is stored in CDR during call processing. No dedicated Lua handler for customer codes exists.

---

Documentation last updated: January 2026

Customer Codes Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Customer Codes?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Administrator Workflow

User Workflow (Using Customer Code)

Quick Tips

4. Configuration Fields Reference

Customer Code Fields

Code Format

5. Usage Flow

Customer Code Entry Flow

CDR Integration

6. Import/Export Feature

CSV Export

CSV Import

7. Common Scenarios & Examples

Scenario 1: Law Firm Client Matters

Scenario 2: Consulting Project Tracking

Scenario 3: Sales Campaign Attribution

8. Limitations & Important Notes

Technical Limitations

Best Practices

9. Troubleshooting Tips

Common Issues

Diagnostic SQL

10. Glossary

Lua Handler Status

⚡ No Dedicated Handler Required