Phonebooks Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Phonebook Types
Compatible Phone Brands
CSV Import
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Phonebooks?

Phonebooks are corporate directories that provide contact lists to IP phones. The system automatically detects the phone brand and returns the correct XML format. Phonebooks can be populated from internal PBX modules or external CSV imports.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    Phonebook System                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  IP Phone                                Backend Server          │
│  ┌─────────────────┐                   ┌──────────────────────┐ │
│  │ Yealink T46U    │                   │  Phonebook Service   │ │
│  │                 │◄──HTTP Request───►│                      │ │
│  │ [Phonebook]     │   User-Agent:     │  1. Detect phone     │ │
│  │                 │   Yealink/T46U    │     brand from UA    │ │
│  │                 │                   │  2. Query phonebook  │ │
│  │                 │◄──XML Response────│  3. Format for brand │ │
│  │                 │   (Yealink XML)   │  4. Return XML       │ │
│  └─────────────────┘                   └──────────────────────┘ │
│                                                                 │
│  Phonebook Sources:                                             │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                                                            │ │
│  │  Internal (from PBX)          External (from CSV)         │ │
│  │  ├─ Extensions                ├─ Customers                │ │
│  │  ├─ Queues                    ├─ Vendors                  │ │
│  │  ├─ Ring Groups               ├─ Partners                 │ │
│  │  ├─ Conferences               └─ Any imported contacts    │ │
│  │  ├─ Feature Codes                                         │ │
│  │  └─ Speed Dials                                           │ │
│  │                                                            │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Features

Feature	Description
Auto-Format Detection	Detects phone brand, returns correct XML
23+ Phone Brands	Yealink, Grandstream, Polycom, Cisco, etc.
Internal Sources	Extensions, Queues, Ring Groups, etc.
CSV Import	Import external contacts
Unique URLs	Random code for security

Key Tables

Table	Purpose
`public.phonebooks`	Phonebook configurations
`public.phonebook_entries`	External contact entries

Key Files

File	Description
`modules/phonebooks/PhonebooksPage.tsx`	Main page
`modules/phonebooks/PhonebookFormView.tsx`	Create/edit form
`modules/phonebooks/PhonebookEntriesView.tsx`	View entries
`modules/phonebooks/PhonebookImportView.tsx`	CSV import

---

2. Module Overview (Commercial/Business)

Business Value

Phonebooks provide centralized contact management:

Without Phonebooks	With Phonebooks
Manual phone config	Auto directory
Static contacts	Dynamic updates
Per-phone setup	Central management
No external contacts	CSV import

Use Cases

Internal Directory

- All extensions visible

- Updated automatically

Department Phonebooks

- Sales team only

- Support team only

External Contacts

- Customer list

- Vendor directory

Feature Access

- Quick dial codes

- Conference access

Feature Highlights

Feature	Benefit
Multi-Brand	One phonebook for all phones
Auto-Format	No per-brand configuration
Internal + External	Combined directories
CSV Import	Bulk contact upload
Secure URLs	Random access codes

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create internal phonebooks from PBX modules
Create external phonebooks from CSV
Select which modules to include
Import contacts from CSV files
Copy phonebook URL for phones
View and manage entries

Phonebook Creation Interface

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Create Phonebook                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Section: General                                               │
│  ├─ Description: Sales Team Directory                          │
│  ├─ Type: [Internal ▼] / External                              │
│  ├─ Prefix: (optional)                                         │
│  └─ URL: (auto-generated after save)                           │
│                                                                 │
│  Section: PBX Modules to Include (Internal only)               │
│  ├─ Extensions: [Select extensions...    ] ▼                   │
│  │   ☑ 1001 - John Smith                                       │
│  │   ☑ 1002 - Jane Doe                                         │
│  │   ☐ 1003 - Bob Wilson                                       │
│  ├─ Queues: [Select queues...            ] ▼                   │
│  ├─ Ring Groups: [Select ring groups...  ] ▼                   │
│  ├─ Conferences: [Select conferences...  ] ▼                   │
│  ├─ Feature Codes: [Select feature codes...] ▼                 │
│  └─ Speed Dials: [Select speed dials...  ] ▼                   │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

URL Configuration

After saving, the phonebook URL is auto-generated:

Plaintext

https://pbx.example.com/api/phonebook/a7b3c9d2e5f1

This URL is configured in the phone's phonebook settings.

Quick Tips

TIP

Auto-Format: The system detects phone brand automatically - one URL works for all phones.

TIP

Copy URL: Use "Copy URL" button to easily share with phone configurations.

CAUTION

Save First: Must save phonebook before URL is generated.

---

4. Phonebook Types

Internal Phonebook

Dynamically generated from PBX modules:

Module	Description
Extensions	SIP extensions with names
Queues	Call center queues
Ring Groups	Ring groups
Conferences	Conference bridges
Feature Codes	Star codes (60, 72, etc.)
Speed Dials	Speed dial numbers

Benefits:

Always up-to-date
No manual maintenance
Reflects current PBX config

External Phonebook

Imported from CSV file:

Field	Description
Name	Contact name
Number	Phone number
Mobile	Mobile number
Organization	Company name
Email	Email address

Benefits:

Customer directories
Vendor contacts
Any external list

---

5. Compatible Phone Brands

Supported Brands (23+)

Category	Brands
Enterprise	Yealink, Polycom, Cisco, Avaya
Consumer	Grandstream, Fanvil, Snom, Htek
Softphones	Linphone, Zoiper, Bria
Legacy	Aastra, Mitel, Alcatel
Other	Panasonic, Gigaset, Sangoma, etc.

Auto-Detection

The system detects the phone brand from the HTTP User-Agent header:

Plaintext

User-Agent: Yealink SIP-T46U 28.73.0.50
→ Returns Yealink XML format

User-Agent: Grandstream GXP2170 1.0.1.35
→ Returns Grandstream XML format

Format Demo

Each brand receives the correct XML format:

Yealink Example:

Xml

<?xml version="1.0" encoding="UTF-8"?>
<YealinkIPPhoneDirectory>
  <DirectoryEntry>
    <Name>John Smith</Name>
    <Telephone>1001</Telephone>
  </DirectoryEntry>
</YealinkIPPhoneDirectory>

Grandstream Example:

Xml

<?xml version="1.0" encoding="UTF-8"?>
<AddressBook>
  <Contact>
    <Name>John Smith</Name>
    <Phone>1001</Phone>
  </Contact>
</AddressBook>

---

6. CSV Import

CSV Format

Template:

Csv

name,number,mobile,organization,email
John Smith,5551234567,5559876543,Acme Corp,john@acme.com
Jane Doe,5552345678,,Partner Inc,jane@partner.com

Required Fields

Field	Required	Description
name	✅ Yes	Contact name
number	✅ Yes	Primary phone
mobile	❌ Optional	Mobile number
organization	❌ Optional	Company
email	❌ Optional	Email address

Import Process

Create/edit external phonebook
Click Import CSV
Download template (optional)
Upload CSV file
Review import results

Import Results

Result	Description
Imported	New contacts added
Skipped	Duplicates ignored
Errors	Invalid entries

---

7. Common Scenarios & Examples

Scenario 1: Company-Wide Directory

Internal Phonebook:

Setting	Value
Description	Company Directory
Type	Internal
Extensions	All
Queues	All
Ring Groups	All

Scenario 2: Sales Team Only

Internal Phonebook:

Setting	Value
Description	Sales Team
Type	Internal
Extensions	Sales department only
Queues	Sales Queue

Scenario 3: Customer Directory

External Phonebook:

Setting	Value
Description	Customer Contacts
Type	External
Source	Import from CRM CSV

Scenario 4: Feature Code Quick Access

Internal Phonebook:

Setting	Value
Description	Feature Codes
Type	Internal
Feature Codes	All enabled codes

---

8. Limitations & Important Notes

Technical Notes

NOTE

URL Security: Random codes prevent unauthorized access.

NOTE

Auto-Format: No need to create separate phonebooks per brand.

WARNING

Save First: Phonebook must be saved before URL is generated.

Best Practices

Descriptive Names: Clear phonebook descriptions
Limit Scope: Don't include everything - filter appropriately
Regular Updates: Keep external contacts current
Test URLs: Verify phonebook loads on phones
Document: Track which phonebooks go to which phones

---

9. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
No URL	Not saved	Save phonebook first
Empty phonebook	No modules selected	Select at least one source
Wrong format	Unknown phone	Check User-Agent
Import fails	Bad CSV format	Use template
Missing entries	Wrong module	Verify module selection

Testing Phonebook URL

Bash

# Test with curl (default format)
curl https://pbx.example.com/api/phonebook/a7b3c9d2e5f1

# Test with Yealink User-Agent
curl -A "Yealink SIP-T46U 28.73.0.50" \
  https://pbx.example.com/api/phonebook/a7b3c9d2e5f1

Diagnostic SQL

List phonebooks:

Sql

SELECT id, description, type, url, enabled
FROM public.phonebooks
WHERE domain_id = [domain_id];

Count entries:

Sql

SELECT phonebook_id, COUNT(*) as entries
FROM public.phonebook_entries
GROUP BY phonebook_id;

---

10. Glossary

Term	Definition
Phonebook	Contact directory for IP phones
Internal	Generated from PBX modules
External	Imported from CSV
User-Agent	HTTP header identifying phone brand
XML Format	Phone-specific directory format
Entry	Single contact in phonebook

---

Lua Script Status ℹ️

No Lua Handler Required

Component	Status
Phonebooks	ℹ️ Backend service - XML served by API based on phone brand

Phonebooks are served by the backend API which auto-detects phone brand and returns the appropriate XML format. No Lua handlers are used.

---

Documentation last updated: January 2026

Phonebooks Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Phonebooks?

Architecture

Key Features

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?

Phonebook Creation Interface

URL Configuration

Quick Tips

4. Phonebook Types

Internal Phonebook

External Phonebook

5. Compatible Phone Brands

Supported Brands (23+)

Auto-Detection

Format Demo

6. CSV Import

CSV Format

Required Fields

Import Process

Import Results

7. Common Scenarios & Examples

Scenario 1: Company-Wide Directory

Scenario 2: Sales Team Only

Scenario 3: Customer Directory

Scenario 4: Feature Code Quick Access

8. Limitations & Important Notes

Technical Notes

Best Practices

9. Troubleshooting Tips

Common Issues

Testing Phonebook URL

Diagnostic SQL

10. Glossary

Lua Script Status ℹ️

No Lua Handler Required