--- title: "Phonebooks Module Documentation" description: "Documentation for Phonebooks" --- ## 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. [Compatible Phone Brands & Auto-Detection](#5-compatible-phone-brands--auto-detection) 6. [CSV Import Specification](#6-csv-import-specification) 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 Phonebooks? Phonebooks are **centralized corporate directories** that dynamically deliver contact lists to IP desktop phones, DECT handsets, and softphone clients. The Ring2All Phonebook subsystem features an intelligent **Content Negotiation Engine**: when an IP phone queries its assigned HTTP phonebook URL, the backend inspects the client's `User-Agent` header and automatically synthesizes the proprietary XML, CSV, or JSON directory format expected by that specific manufacturer model (e.g. Yealink, Grandstream, Cisco, Polycom, Fanvil, Snom). ### Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ Phonebook System Architecture │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ IP Phone Backend Web Service │ │ ┌──────────────────┐ ┌─────────────────────┐ │ │ │ Yealink T46U │ │ Phonebook Engine │ │ │ │ │◄──HTTP Request───►│ │ │ │ │ [Directory Key] │ User-Agent: │ 1. Match Hash Code │ │ │ │ │ Yealink/T46U │ 2. Detect Device │ │ │ │ │ │ 3. Assemble Data │ │ │ │ │◄──XML Response────│ 4. Render Format │ │ │ │ │ (Yealink XML) │ │ │ │ └──────────────────┘ └─────────────────────┘ │ │ │ │ │ Directory Sources: ▼ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ Internal PBX Modules External CSV Contacts │ │ │ │ ├─ Active Extensions ├─ Customers & VIPs │ │ │ │ ├─ Call Center Queues ├─ Suppliers & Vendors │ │ │ │ ├─ Ring Groups ├─ Remote Branches │ │ │ │ ├─ Conference Bridges └─ Custom External Lists │ │ │ │ ├─ Feature Star Codes │ │ │ │ └─ Speed Dial Shortcodes │ │ │ │ │ │ │ └────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Module Overview (Commercial/Business) ### Business Value Manual management of phone address books is inefficient and prone to errors. When new personnel join or department numbers change, traditional PBXs require re-provisioning each desk phone individually. | Without Ring2All Phonebooks | With Ring2All Phonebooks | |-----------------------------|--------------------------| | Manual contact entry on every phone | One central directory published via HTTP | | Outdated numbers when extensions change | Real-time directory sync straight from PBX database | | Vendor lock-in requiring brand-specific tools | Multi-vendor auto-detection (23+ hardware brands) | | Separate spreadsheets for external clients | Unified internal extensions + external CSV contacts | ### Use Cases 1. **Company-Wide Enterprise Directory**: Automatically publishes all internal staff extensions, ring groups, and conference bridges to all desk phones. 2. **Departmental Contact Lists**: Filter directories so customer support phones receive vendor and VIP client numbers, while executive suites receive private boardroom shortcodes. 3. **External Client Books**: Import CRM contact lists so incoming and outgoing phone displays show company names and client details directly on handset screens. 4. **Feature Code Quick Access**: Distribute star codes (`*88`, `*91`, `*72`) to phones with human-readable labels so employees don't need to memorize system commands. --- ## 3. Module Overview (End User/Administrator) ### What Can You Do? - Create **Internal Directories** dynamically populated from PBX Extensions, Queues, Ring Groups, Conferences, Feature Codes, and Speed Dials. - Create **External Directories** imported from external CSV contact spreadsheets. - Provide a single secure, auto-generated HTTP URL configured once into phone templates. - Preview raw phone-specific XML formats directly in the administrative interface. - Search, filter, export, and manage contact entries seamlessly. ### Navigation 1. In the main navigation bar, select **PBX Engine → Applications → Phonebooks** (or navigate directly to `/pbx/applications/phonebooks`). 2. The **list view** displays all configured directories, including Description, Directory Type (Internal/External), Unique URL, and active Status (Enabled/Disabled). 3. Click the **+ Add** button in the upper toolbar to build a new phonebook. 4. Click any existing record row or edit button to update included modules or import new contact batches. ![Phonebooks List View](/screenshots/pbx/applications/phonebooks-list.png) ### Administrator Workflow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Creating a Corporate Phonebook │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Step 1: General Information │ │ ├─ Description: "Corporate Master Directory" │ │ ├─ Type: Internal │ │ ├─ URL: (Auto-generated unique hash endpoint) │ │ └─ Enabled: Active │ │ │ │ Step 2: Select PBX Modules to Include │ │ ├─ Extensions: All active company extensions │ │ ├─ Queues: Sales Queue, Support Queue │ │ ├─ Ring Groups: Tier 1 Dispatch │ │ ├─ Conferences: Executive Boardroom │ │ └─ Speed Dials: External Emergency Hotline │ │ │ │ Step 3: Save and Copy URL │ │ ├─ Click "Copy URL" button │ │ └─ Paste into Auto-Provisioning template for Yealink/Cisco │ │ │ │ Result: IP phones automatically fetch updated XML on reboot │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Quick Tips > [!TIP] > **One URL for All Models**: The backend detects the handset's brand from the `User-Agent` header. You can assign the identical URL to Yealink, Grandstream, and Polycom phones—each receives its proprietary XML dialect automatically. > [!TIP] > **Real-Time Extension Updates**: Internal phonebooks evaluate active extensions dynamically. When an administrator renames or adds an extension, phones fetch the new record on their next scheduled poll without modifying the phonebook configuration. > [!CAUTION] > **URL Confidentiality**: The unique code in the phonebook URL acts as an access token. Do not publish directory URLs on unauthenticated public websites. --- ## 4. Configuration Fields Reference ![Phonebook Configuration Form](/screenshots/pbx/applications/phonebooks-form.png) ### General Information Box | Field | Description | UI Tooltip | Example | Notes | |-------|-------------|------------|---------|-------| | **Description \*** | Human-readable directory name | Descriptive label for this corporate address book | `Corporate Master Directory` | Required. | | **Type \*** | Directory source classification | Choose Internal (PBX modules) or External (CSV imported contacts) | `Internal` | Dropdown: `Internal` or `External`. Required. | | **URL \*** | Auto-generated secure directory endpoint | Unique HTTP URL providing phone-compatible directory XML | `http://192.168.10.31:3000/api/phonebooks/xml/sec_948f2a` | Features a dedicated "Copy URL" button. Compatible with 23+ hardware phone brands. | | **Enabled** | Operational toggle | Activate or deactivate phonebook XML generation | `Enabled` / `Disabled` | Toggle. Default: `Enabled`. | ### PBX Modules to Include Box (Internal Phonebooks) When **Type** is set to `Internal`, the system displays multi-select pickers to choose specific PBX entities: | Entity Selector | Description | UI Tooltip | Notes | |-----------------|-------------|------------|-------| | **Extensions** | SIP user extensions to include | Extensions to include in this phonebook | Multi-select modal showing Extension number and Caller ID Name. | | **Queues** | Call center queues to include | Queues to include in this phonebook | Includes Queue display name and virtual dial extension. | | **Ring Groups** | Ring groups to include | Ring groups to include in this phonebook | Includes group extension number and description. | | **Conferences** | Conference bridges to include | Conferences to include in this phonebook | Includes bridge extension and room name. | | **Feature Codes** | System star codes to include | Feature codes to include in this phonebook | Includes active feature codes (`*88`, `*72`, etc.). | | **Speed Dials** | Fast dial shortcodes to include | Speed dials to include in this phonebook | Includes shortcode number and destination label. | ### Imported Contacts Box (External Phonebooks) When **Type** is set to `External`, the administrative form renders an embedded contact data grid: | Control | Description | Purpose | |---------|-------------|---------| | **Search Contacts** | Real-time text search input | Filter contacts by First Name, Last Name, Phone, or Organization. | | **Items Per Page** | Pagination limit dropdown | Display 10, 25, 50, or 100 contacts per page. | | **Import CSV Button** | Action toolbar modal opener | Opens file upload modal for CSV contact ingestion. | | **Export Button** | Action toolbar CSV downloader | Exports current contacts to a standard `.csv` file. | | **Preview Format** | Top header action button | Inspect raw XML output for Yealink, Grandstream, Cisco, and Polycom formats. | --- ## 5. Compatible Phone Brands & Auto-Detection The Ring2All Phonebook engine contains built-in rendering templates for over 23 major hardware vendors and softphones: | Vendor Category | Supported Brands & Series | Native Output Format | |-----------------|---------------------------|----------------------| | **Tier 1 Enterprise** | Yealink (T2x, T3x, T4x, T5x, CP9xx), Polycom / Poly (VVX, SoundPoint), Cisco (SPA5xx, CP-78xx, CP-88xx) | Yealink XML, Polycom Directory XML, Cisco XML Directory | | **Telecom & SMB** | Grandstream (GXP, GRP, WP series), Fanvil (X, V series), Snom (D3xx, D7xx) | Grandstream AddressBook XML, Fanvil IPPhoneBook, Snom IPPhoneDirectory | | **Wireless / DECT** | Gigaset Pro, Panasonic (KX-TGP), Flyingvoice, Spectralink | Vendor XML / CSV | | **Intercom & Paging**| CyberData, Algo Communication, 2N, AudioCodes | Device XML / Plaintext | | **Softphone / Mobile**| Ring2All WebRTC Portal, Linphone, Zoiper, Bria | REST JSON Directory / Switchboard API | ### Auto-Detection in Action When a phone issues an HTTP GET request, the engine checks the `User-Agent` string: ```http GET /api/phonebooks/xml/sec_948f2a HTTP/1.1 Host: 192.168.10.31:3000 User-Agent: Yealink SIP-T46U 66.86.0.15 ``` The system recognizes `Yealink` and delivers: ```xml Corporate Master Directory Alice Smith 1001 Sales Priority Queue 8001 ``` --- ## 6. CSV Import Specification For External phonebooks, contacts can be imported in bulk using comma-separated values (CSV). ### Sample CSV Template ```csv firstName,lastName,phoneNumber,mobileNumber,organization,email John,Doe,+15551234567,+15559876543,Acme Corp,jdoe@acme.com Jane,Smith,+15552345678,,Global Logistics,jsmith@globallogistics.com Robert,Johnson,+15553456789,+15558765432,VIP Client,rjohnson@client.com ``` ### Column Rules | Field | Required | Description | Validation | |-------|----------|-------------|------------| | `firstName` | Optional | Contact's given name | Text up to 64 chars | | `lastName` | Optional | Contact's family name | Text up to 64 chars (At least one name required) | | `phoneNumber` | Required | Work / Landline phone number | Valid E.164 or numeric string | | `mobileNumber` | Optional | Cell / Secondary phone number | Valid E.164 or numeric string | | `organization` | Optional | Business / Company label | Text up to 100 chars | | `email` | Optional | Contact email address | Valid RFC 5322 email syntax | --- ## 7. Common Scenarios & Examples ### Scenario 1: All-Hands Corporate Address Book - **Type**: Internal - **Included Entities**: All Extensions, All Call Center Queues, All Ring Groups. - **Use Case**: Pushed to every office workstation so any employee can search for colleagues by first or last name using their phone keypad. ### Scenario 2: Remote Warehouse DECT Directory - **Type**: Internal - **Included Entities**: Shipping Extensions (`1040–1055`), Security Ring Group (`7000`), Gate Intercom (`8010`). - **Use Case**: Eliminates clutter for warehouse floor staff, giving them immediate access to operational extensions. ### Scenario 3: Executive VIP External Contacts - **Type**: External - **Source**: Imported CSV containing board members, key legal counsel, and banking partners. - **Use Case**: Configured exclusively on executive suite phones to provide instant dialing of external private mobile numbers without exposing numbers to the entire company. ## 8. Model Context Protocol (MCP) AI Integration Ring2All exposes native Model Context Protocol (MCP) tools for **Phonebooks**, enabling AI assistants and Copilots to query directories, search contacts across multiple internal and external address books, and programmatically provision corporate directories or individual contact records with domain isolation. ### Available MCP Tools | Tool Name | Description | Key Parameters | |:---|:---|:---| | `list_phonebooks` | Lists all phonebook directories configured in the domain, including directory types (internal/external), URLs, and descriptions. | `query` (optional string) | | `get_phonebook_status` | Retrieves configuration details, provisioning URL endpoints, and contact counts for a phonebook. | `identifier` (required, name or ID) | | `search_phonebook_contacts` | Searches contacts across phonebooks by first/last name, phone number, email address, or organization. | `query` (required), `phonebookName` (optional) | | `create_phonebook` | Provisions a new corporate directory (internal auto-synced or external custom list). | `name`, `type` ('internal' or 'external'), `url` | | `add_phonebook_contact` | Adds a new contact entry into an external phonebook. | `phonebookName`, `firstName`, `lastName`, `phoneNumber`, `mobileNumber`, `organization`, `email` | | `delete_phonebook_contact` | Removes a contact from an external phonebook by name or telephone number. | `phonebookName`, `contactQuery` | | `delete_phonebook` | Deletes a phonebook directory and its associated contacts from the domain. | `identifier` (required) | ### AI Agent Operational Examples #### Searching Contacts Across Company Directories ```json { "tool": "search_phonebook_contacts", "arguments": { "query": "Logistics", "phonebookName": "Corporate Master Directory" } } ``` #### Programmatically Adding an External Partner Contact ```json { "tool": "add_phonebook_contact", "arguments": { "phonebookName": "Key Vendors", "firstName": "Marcus", "lastName": "Vance", "phoneNumber": "+15554320199", "organization": "Global Freight Logistics", "email": "mvance@globalfreight.com" } } ``` ### Recommended Natural Language Prompts - *"Find the phone number for John Doe or search for anyone with the last name Smith in our phonebooks."* - *"Add a new external vendor contact 'Acme Supplies' with number +1-800-555-0144 to the Vendors phonebook."* - *"List all phonebook directories configured on this PBX and show their device provisioning URLs."* --- ## 9. Limitations & Important Notes > [!NOTE] > **No Manual Phone Re-Flashing**: Phones automatically re-poll directory XML upon scheduled refresh intervals (typically every 12 to 24 hours or upon device reboot). > [!NOTE] > **Dual Endpoint Capability**: Both `/api/phonebooks/xml/{hash}` (for IP phones) and `/api/phonebooks/json/{hash}` (for WebRTC softphones) are supported out of the box. > [!WARNING] > **Phone Memory Limits**: Some entry-level IP phones have hardware limitations (e.g., maximum 500 or 1000 XML entries). For large organizations with 2000+ extensions, create targeted departmental phonebooks rather than loading one massive list into budget hardware. --- ## 10. Troubleshooting Tips | Symptom | Probable Cause | Diagnostic & Resolution | |---------|----------------|-------------------------| | Phone displays "XML Format Error" | Unrecognized User-Agent or invalid character in name | Test URL via curl specifying user-agent: `curl -A "Yealink" http://...`. Verify no unescaped XML characters (`&`, `<`, `>`) exist in imported names. | | Directory on phone is empty | No PBX modules selected or phonebook disabled | Ensure `Enabled` toggle is active and at least one extension or queue is checked in the module selector. | | URL cannot be reached from phone | Network firewall blocking HTTP/HTTPS port | Ensure IP phone subnet has routing access to the PBX web service port (e.g. port 80/443/3000). | | Contact updates not appearing on phone | Handset local caching | Reboot the phone or press the **Update** softkey on the phone's directory menu to bypass cache. | ### Diagnostic SQL Queries **Verify Phonebook Record & Hash:** ```sql SELECT id, description, type, url, enabled, updated_at FROM public.phonebooks WHERE domain_id = [domain_id]; ``` **Count Imported External Entries:** ```sql SELECT phonebook_id, COUNT(*) AS total_contacts FROM public.phonebook_entries GROUP BY phonebook_id; ``` --- ## 11. Glossary | Term | Definition | |------|------------| | **Phonebook** | Centralized XML or JSON contact directory published over HTTP to IP endpoints. | | **Content Negotiation** | Server capability to detect device model via User-Agent and format the response specifically for that vendor. | | **Internal Phonebook** | Directory populated in real time directly from active PBX extensions and routing entities. | | **External Phonebook** | Directory assembled from uploaded CSV contact files containing external numbers and business partners. | | **LDAP / Remote XML** | Industry-standard protocol specifications utilized by IP telephony handsets to fetch external contacts. |