Ctrl K
ring2all.com

CID Modifiers Module Documentation

Table of Contents

  1. Module Overview (Technical)
  2. Module Overview (Commercial/Business)
  3. Module Overview (End User/Administrator)
  4. Configuration Fields Reference
  5. Source Types
  6. Action Types
  7. Common Scenarios & Examples
  8. Limitations & Important Notes
  9. Troubleshooting Tips
  10. Glossary

---

1. Module Overview (Technical)

What Are CID Modifiers?

CID Modifiers are Caller ID manipulation rules that transform caller ID number and/or name before the call is routed. They support pattern matching, number normalization, and dynamic lookups from databases or external APIs.

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                CID Modifier Processing                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Incoming Call:                                                 │
│  ├─ Caller ID Number: 5058881234                               │
│  └─ Caller ID Name: WIRELESS CALLER                            │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        CID Modifier Rules (by priority)                  │   │
│  │                                                          │   │
│  │  Rule 1 (priority 10): Normalize to E.164                │   │
│  │    Pattern: ^505.*                                       │   │
│  │    Action: prepend +                                     │   │
│  │    Result: +5058881234                                   │   │
│  │                                                          │   │
│  │  Rule 2 (priority 20): CRM Name Lookup                   │   │
│  │    Source: HTTP                                          │   │
│  │    URL: https://crm.company.com/lookup?num=[CIDNUM]      │   │
│  │    Result: "John Smith" (from CRM)                       │   │
│  │                                                          │   │
│  │  Rule 3 (priority 30): Add Department Prefix             │   │
│  │    Pattern: .*                                           │   │
│  │    Action: prepend "Sales: " to name                     │   │
│  │    Result: "Sales: John Smith"                           │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Modified Call:                                                 │
│  ├─ Caller ID Number: +5058881234                              │
│  └─ Caller ID Name: Sales: John Smith                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

TablePurpose
public.cid_modifiersCID modifier rules

Key Files

FileDescription
admin/apps/web/src/modules/cidModifiers/Frontend module
admin/apps/web/src/i18n/en/cidModifiers.jsonTranslations
NOTE

CID modifications are applied during call routing in the main dialplan handlers.

---

2. Module Overview (Commercial/Business)

Business Value

CID Modifiers enable intelligent caller identification:

Without CID ModifiersWith CID Modifiers
Raw caller IDNormalized E.164 format
"WIRELESS CALLER"Customer name from CRM
No contextDepartment prefix
Inconsistent formatStandardized numbers

Use Cases

  1. Number Normalization

- Convert local to E.164 (+15058881234)

- Strip trunk prefixes

  1. CRM Integration

- Lookup customer name from database

- Display account number

  1. Department Branding

- Prepend "Sales:" to name

- Add queue identifier

  1. Outbound CID Control

- Set specific caller ID per route

- Corporate branding

Feature Highlights

FeatureBenefit
Pattern MatchingRegex condition matching
Multiple SourcesStatic, Database, HTTP
Priority OrderSequential rule processing
Stop On MatchControl rule cascade
E.164 NormalizationStandard number format
HTTP LookupExternal API integration
---

3. Module Overview (End User/Administrator)

What Can You Do?

  • Create CID modification rules
  • Set pattern conditions
  • Choose action types (prepend, append, replace, etc.)
  • Configure priority order
  • Set up database or HTTP lookups
  • Simulate modifications before saving

Administrator Workflow

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              Creating a CID Modifier                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Tab: General                                                   │
│  ├─ Name: "Add Country Code"                                   │
│  ├─ Source: Static                                             │
│  ├─ Direction: Inbound                                         │
│  ├─ Condition Field: Caller ID Number                          │
│  ├─ Condition Pattern: ^[2-9][0-9]{9}$                         │
│  ├─ Action Type: Prepend                                       │
│  ├─ Action Value: +1                                           │
│  ├─ Priority: 10                                               │
│  ├─ Stop on Match: Off                                         │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Tab: Advanced Settings (for Static source)                     │
│  ├─ CID Number Settings:                                       │
│  │   ├─ Skip: 0                                                │
│  │   ├─ Length: 0 (all digits)                                 │
│  │   ├─ Prepend: +1                                            │
│  │   └─ Append: (empty)                                        │
│  ├─ CID Name Settings:                                         │
│  │   ├─ Prepend: (empty)                                       │
│  │   ├─ Append: (empty)                                        │
│  │   ├─ Replace With: (empty)                                  │
│  │   ├─ Force E.164 Format: Off                                │
│  │   ├─ Strip Non-Digit Characters: On                         │
│  │   └─ Block Name if Empty: On                                │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Section: Simulation                                            │
│  ├─ Test Number: 5058881234                                    │
│  ├─ Test Name: WIRELESS CALLER                                 │
│  ├─ [Run Simulation]                                           │
│  ├─ Modified Number: +15058881234                              │
│  └─ Modified Name: WIRELESS CALLER                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Use Simulation: Test your rules before saving to verify expected output.
TIP
Priority Matters: Lower numbers execute first. Plan your rule order.
CAUTION
Pattern Syntax: Use valid regex patterns or rules won't match.

---

4. Configuration Fields Reference

General Fields

FieldDescriptionExample
NameRule identifierAdd Country Code
SourceData source typeStatic/Database/HTTP
DirectionCall directionInbound/Outbound/Internal
Condition FieldField to evaluatecaller_id_number
Condition PatternRegex pattern^[2-9][0-9]{9}$
Action TypeModification typeprepend
Action ValueValue to apply+1
PriorityExecution order (0-999)10
Stop on MatchStop further rulesOn/Off
EnabledRule activeOn/Off

Directions

DirectionDescription
InboundExternal calls coming in
OutboundInternal calls going out
InternalExtension to extension

Condition Fields

FieldDescription
caller_id_numberCaller's phone number
caller_id_nameCaller's name
destination_numberNumber being called
source_numberSource number
---

5. Source Types

Static Source

Manual configuration of transformation rules:

SettingDescription
SkipDigits to skip from start
LengthOutput length (0 = all)
PrependAdd before number
AppendAdd after number
Force E.164Convert to +E.164 format
Strip Non-DigitsRemove non-numeric chars

Database Source

Lookup caller info from external database:

SettingDescription
DatabaseDatabase name
HostServer address
UsernameAuth username
PasswordAuth password
QuerySQL returning cidname, cidnumber

HTTP Source

Lookup from external API:

SettingDescription
URLAPI endpoint with [CIDNUM]/[CIDNAME]
Auth UserHTTP auth username
Auth PasswordHTTP auth password
TimeoutRequest timeout (seconds)
RetriesRetry attempts
Failover BehaviorWhat to do if lookup fails
---

6. Action Types

Available Actions

ActionDescriptionExample
PrependAdd before value+1 + 5058881234 = +15058881234
AppendAdd after value5058881234 + -ext = 5058881234-ext
ReplaceComplete replacementReplace with custom value
StripRemove leading digitsStrip 1 from 15058881234 = 5058881234
Set NameSet caller name"VIP Customer"
Set NumberSet caller number"+18005551234"
NormalizeConvert to E.1645058881234 → +15058881234
CustomCustom transformationVariable-based
---

7. Common Scenarios & Examples

Scenario 1: E.164 Normalization

Rule: "Add US Country Code"
SettingValue
DirectionInbound
Condition Pattern^[2-9][0-9]{9}$
Action TypePrepend
Action Value+1
Priority10
Result: 5058881234 → +15058881234

Scenario 2: CRM Name Lookup

Rule: "CRM Customer Lookup"
SettingValue
SourceHTTP
DirectionInbound
URLhttps://crm.example.com/api/caller?num=[CIDNUM]
Timeout3
FailoverKeep Original
Priority20
Result: "WIRELESS CALLER" → "John Smith"

Scenario 3: Department Prefix

Rule: "Sales Queue Prefix"
SettingValue
DirectionInbound
Action TypePrepend (to name)
Action Value"Sales: "
Priority30
Result: "John Smith" → "Sales: John Smith"

Scenario 4: Strip Trunk Prefix

Rule: "Remove 9 Prefix"
SettingValue
DirectionOutbound
Condition Pattern^9[0-9]+$
Action TypeStrip
Action Value1
Priority5
Result: 915058881234 → 15058881234

---

8. Limitations & Important Notes

Technical Notes

NOTE
Processing Order: Rules execute by priority (lower first).
WARNING
Regex Patterns: Invalid patterns will cause rule to not match.
WARNING
HTTP Timeouts: Consider call setup time when using HTTP lookups.

Best Practices

  1. Test First: Use simulation before saving
  2. Order Carefully: Plan priority sequence
  3. Use Stop on Match: Prevent redundant processing
  4. Monitor Timeouts: HTTP lookups add latency
  5. Log Changes: Enable for troubleshooting

---

9. Troubleshooting Tips

Common Issues

SymptomPossible CauseSolution
No modificationPattern not matchingTest regex pattern
Wrong resultPriority orderCheck rule priorities
HTTP timeoutSlow external APIReduce timeout, add caching
Empty nameLookup failedCheck failover behavior
Rule skippedDisabled or invalidVerify enabled status

Diagnostic SQL

List CID modifiers:

Sql
SELECT id, name, direction, action_type, condition_pattern, priority, enabled
FROM public.cid_modifiers
WHERE domain_id = [domain_id]
ORDER BY priority;

FreeSWITCH Logs

Bash
# Check CID processing
grep "effective_caller_id" /var/log/freeswitch/freeswitch.log
grep "caller_id_number" /var/log/freeswitch/freeswitch.log

---

10. Glossary

TermDefinition
CIDCaller ID - phone number and name
E.164International phone number format (+15058881234)
CLIDCaller Line ID (same as CID)
NormalizeConvert to standard format
PrependAdd to beginning
AppendAdd to end
StripRemove from beginning
---

Lua Script Status ℹ️

Configuration Module

ComponentStatus
CID Modifiersℹ️ Configuration stored in public.cid_modifiers, applied during routing process
CID modifications are applied at various points in the routing handlers rather than having a dedicated handler. The rules are read from the database and applied to incoming/outgoing calls.

---

Documentation last updated: January 2026
AI Assistant

👋 Hello! I'm your Ring2All documentation assistant. I can help you find information about configuring and using the Ring2All PBX platform.

How can I help you today?