---
title: "Customer Codes Module Documentation"
description: "Documentation for Customer Codes"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
3. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
4. [Configuration Fields Reference](#4-configuration-fields-reference)
5. [Usage Flow](#5-usage-flow)
6. [Import/Export Feature](#6-importexport-feature)
7. [Common Scenarios & Examples](#7-common-scenarios--examples)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Limitations & Important Notes](#9-limitations--important-notes)
10. [Troubleshooting Tips](#10-troubleshooting-tips)
11. [Glossary](#11-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

```
┌─────────────────────────────────────────────────────────────────┐
│                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               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 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

1. **Law Firms / Professional Services**
   - Associate calls with client matters
   - Bill phone time to specific cases

2. **Agencies / Consultants**
   - Track calls by project
   - Client-specific billing

3. **Cost Centers**
   - Allocate telecom costs to departments
   - Project-based accounting

4. **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

### Navigation

1. Navigate to **PBX Engine → Class of Services → Customer Codes** in the main navigation menu.
2. The **list view** displays all configured customer codes with Code, Description, and active status.
3. Click the **+ Add** button in the top toolbar to register a new billing/customer code.
4. Click any code entry or edit icon to adjust the code value, description, or activation toggle.

![Customer Codes List View](/screenshots/pbx/class-of-service/customer-codes-list.png)

### Administrator Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│              Creating a Customer Code                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: Code Information                                       │
│  ├─ Customer Code: ACCT-84920                                   │
│  ├─ Description: "Corporate Legal Retainer Account"            │
│  └─ Active: ✓                                                  │
│                                                                 │
│  Step 2: Save                                                   │
│                                                                 │
│  Result: Code available for users to enter before calls        │
│          CDR will include "ACCT-84920" for billing             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### User Workflow (Using Customer Code)

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

### Quick Tips

> [!TIP]
> **Meaningful Codes**: Use codes that map directly to your accounting/ERP billing system (e.g., matter numbers, project IDs, customer account numbers).

> [!TIP]
> **Descriptions**: Add clear descriptions explaining the project or client associated with the code for easier auditing.

---

## 4. Configuration Fields Reference

![Customer Code Configuration Form](/screenshots/pbx/class-of-service/customer-codes-form.png)

### Basic Information Fields

| Field | Description | User-Friendly Tooltip | Example | Notes |
|-------|-------------|----------------------|---------|-------|
| **Customer Code \*** | Unique alphanumeric billing or tracking code | Enter the unique customer or project code for call attribution | `ACCT-84920`, `LEGAL-104` | Required. Unique per domain. |
| **Description** | Contextual client or department notes | Detailed description of the client or accounting project | `Corporate Legal Retainer Account` | Optional. |
| **Active \*** | Operational status of the code | Toggle whether this code is currently accepted for call billing | `Toggle (On/Off)` | If inactive, dialed attempts using this code will be rejected. |

### 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

```
┌─────────────────────────────────────────────────────────────────┐
│                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. Model Context Protocol (MCP) AI Integration

Ring2All exposes native Model Context Protocol (MCP) tools for **Customer Codes (Account/Billing Codes)**, allowing AI Copilots to query client project tags, audit CDR billing tracking codes, and programmatically provision or update customer codes with domain-level isolation and duplicate-code validation.

### Available MCP Tools

| Tool Name | Description | Key Parameters |
|:---|:---|:---|
| `list_customer_codes` | Lists all customer / account codes configured in the domain, including code values, descriptions, and active status. | `search` (optional string) |
| `get_customer_code_status` | Retrieves details and active billing status of a specific customer code. | `code` (required) |
| `create_customer_code` | Provisions a new customer code (numeric or alphanumeric) for client project tracking or matter billing. | `code`, `description`, `active` |
| `update_customer_code` | Modifies customer code identifier, project description, or active status. | `code`, `newCode`, `description`, `active` |
| `delete_customer_code` | Deletes a customer code from the domain. | `code` (required) |

### AI Agent Operational Examples

#### Querying Billing Codes by Project Name
```json
{
  "tool": "list_customer_codes",
  "arguments": {
    "search": "Acme"
  }
}
```

#### Provisioning a Legal Matter Billing Code
```json
{
  "tool": "create_customer_code",
  "arguments": {
    "code": "LEG-2026-042",
    "description": "Acme Corp Intellectual Property Dispute",
    "active": true
  }
}
```

### Recommended Natural Language Prompts
- *"List all customer billing codes active on this domain."*
- *"Create a customer code 'PROJ-772' with description 'Hospital Network Upgrade'."*
- *"Check if customer code 'CLI-ACME' exists and show its description."*

---

## 9. 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

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

---

## 10. 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;
```

---

## 11. 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 |

---

*Documentation last updated: January 2026*