Polycom VVX 350 Provisioning and Directory Reference

Overview

This document outlines some of the things I have learned in the process of deploying a few hundred handsets across multiple locations for use with 3CX cloud based PBXs. The handsets would work well with any other systems I imagine. Even refurbished these devices seem to be rock solid. They may not have all the bells and whistles for your use case, but really I think that a lot of modern features are just an example of “Overservicing” and unless you have a very niche need, I don’t really think people need video conference capable phone handsets. For the same price you could have a new laptop or desktop which would provide much more utility, or could be setup in a dedicated mediaroom.

I’ll go through a bit of a general outline of how the phones work based on my discoveries, and then describe some of the specific setups i’ve used.

Provisioning Behavior

Boot Sequence

The VVX 350 follows a predictable boot sequence when configured with a provisioning server:

1. Network Initialization - Obtains IP address via DHCP
2. Provisioning Server Discovery - Uses manually configured or DHCP Option 66 server URL
3. Configuration File Requests - Attempts to download configuration files in specific order
4. Directory File Requests - Automatically requests directory files
5. Application Initialization - Processes configuration and completes boot

Configuration File Request Pattern

The phone requests configuration files in the following priority order:

1. {MAC}.cfg                    (Phone-specific configuration)
2. 000000000000.cfg            (Master/fallback configuration)

Example for MAC address 64167F6B9068:

• 64167F6B9068.cfg
• 000000000000.cfg

Request URL Structure

Configuration requests follow the pattern:

GET /{MAC}.cfg
GET /000000000000.cfg

The phone does NOT automatically append tokens to these requests. Token-based URLs (e.g., /provisioning/{token}/{MAC}.cfg) are specific to certain deployment scenarios and must be handled by proxy servers.

3CX Integration

When integrated with 3CX, each phone typically has a MAC-specific provisioning token, which it appends to the end of the generalised provisioning url.

Pattern: https://server.3cx.cloud/provisioning/{MAC_TOKEN}
Example: https://1394.3cx.cloud/provisioning/p9mxn7kt7r14i9p

These tokens appear to generated algorythmically based proabbly on MAC address and perhaps phone model etc.

Directory Management

Directory File Request Behavior

The VVX 350 automatically requests directory files during boot, the config file it has downloaded from the provisioning server contains a variable that tells the phone where to look, appending this location to the end of the provisioning server url:

1. {MAC}-directory.xml         (Phone-specific directory - highest priority)
2. 000000000000-directory.xml  (Global directory - fallback)

Request timing: Directory requests occur during the provisioning phase, typically within 30-60 seconds of boot.

Directory Storage Model

The phone implements a local storage model for contacts:

1. Initial Download - Downloads directory file(s) once during boot
2. Local Storage - Stores all contacts in internal memory/flash
3. User Modifications - Users can add/edit contacts locally on phone
4. Upload to Server = User created contacts are PUT to the contact directory on the phone server.

Directory Upload Behavior with 3CX

So 3CX doesn’t implement a traditional company phonebook over LDAP, but instead it just serves a copy of the same company wide phonelist as an xml. On the positive side this is a very simple process and there isn’t much that can go wrong.

Key Finding: VVX 350 phones do NOT automatically upload directory changes to 3CX by default, since 3CX doesn’t seemto accept PUT requests coming from the phone to add to their users directory.

• User-added contacts are only stored locally on the phone and overwritten when the phone reprovisions.
• No automatic synchronization of local changes back to server
• Users should add new contacts through the 3CX web interface to the company directory if they wish them to appear on their physical hadnset. 3CX does not create contact directorys for each handset based on the users personal and company contacts, but just creates one generic directory file and either copies it for each phone or more realistically just servcies it with a dynamic filename.
• It is fairly simple to setup a proxy server than can handle the saving of contacts, which we will examine later.
• Upload infrastructure can be implemented server-side, but phones must be specifically configured to use it.

Directory XML Format

Standard Polycom directory format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<directory>
    <item_list>
        <item>
            <ln>Last Name</ln>
            <fn>First Name</fn>
            <ct>Phone Number</ct>
            <sd>Speed Dial/Favorite Index</sd>
        </item>
    </item_list>
</directory>

The phones are very picky about the formatting of their contacts, so if you’re havings issues where the logs indicate that they are downloading the contacts but when it reboots your contact list is empty it would be worth double checking or trying with a minimal config directory.

Directory Fields

Speed Dial and Favorites

The <sd> field serves dual purposes:

• Speed Dial: Contact can be dialed by pressing speed dial number + #
• Favorite Index: Contact appears in favorites list in phone directory
• Range: Typically 1-99, lower numbers have priority
• Behavior: Contacts without <sd> appear as regular directory entries

Configuration Processing

Parameter Processing

The phone processes configuration parameters from multiple sources in priority order:

1. Phone-specific config ({MAC}.cfg)
2. Master config (000000000000.cfg)
3. Local configuration
4. Cloud configuration
5. Web configuration

Invalid Parameter Handling

The phone logs and ignores invalid configuration parameters:

Example log entries:
cfg |4|00|Prm|Configuration: Unknown parameter "APP_FILE_PATH" found, ignoring.
cfg |4|00|Prm|Value "" for configuration parameter lineKey.7.index is invalid, ignoring

Configuration File Format

Basic configuration file structure:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<APPLICATION APP_FILE_PATH="sip.ld" CONFIG_FILES="" LOG_FILE_DIRECTORY="">
<!-- Configuration parameters go here -->
</APPLICATION>

Network Behavior

Request Patterns

All HTTP requests are logged by the phone with detailed timing:

Format: timestamp|component|level|sequence|message
Example: 0919180720|cfg|*|00|Prm|64167f6b9068-config.cfg: processing

Error Handling

The phone implements robust error handling:

• 404 responses: Continues to fallback files
• Network timeouts: Retries with exponential backoff
• DNS failures: Logs errors and continues with available configuration

Request Headers

The phone identifies itself in HTTP requests with:

• User-Agent: Contains model and firmware information
• Content-Type: Varies by request type (config vs directory)

Firmware and Model Information

Tested Configuration

• Model: VVX 350 (Part: 3111-48830-001)
• Firmware: UC Software 6.4.3.5018
• Boot Block: 3.0.6.0098
• Platform: ARMv6-compatible processor

Feature Capabilities

Based on logs and testing:

• Directory Support: Full support for local contact directories
• Speed Dial: Supports speed dial via <sd> field
• BLF: Separate from directory favorites, configured via line key parameters
• Corporate Directory: Can be enabled but requires separate configuration

Logging and Diagnostics

Log Components

The phone generates detailed logs across multiple components:

• cfg: Configuration processing
• copy: File download operations
• app1: Application layer
• so: System operations
• sip: SIP protocol operations

Diagnostic Messages

Key diagnostic indicators:

"Corporate directory is not Enabled" - Corporate directory feature disabled
"File transfer failed due to curl error code:22 and respCode:404" - File not found
"Configuration file(s) statistics: X parameters were invalid" - Config validation results

Pagination of BLF Keys

Polycom VVX 350s support pagination of their BLF Keys, up to 4 pages total, of 6 keys. I can’t conifrm if this is the same for other VVX models. but it is a very handy feature.

Pagination of BLF Keys with 3CX

At December 2025, the 3CX template doesn’t have pagination for BLF keys enabled by default, but those on the Pro plans are able to use a custom template to add in this functionality.

The template used by the VVX 350 is the polycomvvx_gen2.xml

By default there is the line:

<up up.screenCapture.enabled="1" />

If we replace it with:

<up up.screenCapture.enabled="1" up.pagination.enabled="1" />

You will see 4 dots at the top of the screen, and can press right and left on the home scren to scroll through them.

It seems that either 3CX or the phones themselves will not display duplicate entries.

You can of course customise the BLF keys for each user, but for workplaces with under 24 extensions I normally just set them all to be the same.

Proxy Server

Probably more useful in the case that you want to maintain the free hosted “SMB” version of 3cx and you don’t mind the fact that the hold music isn’t customisable.

Proxy Server to serve directory files to all phones

With a proxy server sitting between the phones and the 3CX privisioning server, we are able to serve our own directory.xml files to each phone, which could be MAC specific for each user and also configured to allow the phones to save their local contacts.

Basically we tell the phones to use the proxy as the provisioning server, the proxy passes on the provisioning request to 3CX, modifys the config files on the way back where needed. I believe 3CX config files contain the url of the 3CX provisiong server, so we need the proxy to change this to it’s own address or the phones will update their provisioning server settings.

Then when the phone reaches out and requests the {MAC}-directory.xml file we can either create one based on our 0000000-directory.xml, or just serve the 000000000-diretory.xml if we aren’t concerned about persisting local contacts.

When a local contact is saved, the phone will reach out to the proxy server and try to PUT it’s {MAC}-directory.xml file and overwrite the existing one, Ta-Da! We have now got a company wide contact directory with persistent local contacts.

We will need to create the initial 00000000-directory.xml file, and we will need to update it manually whenever we need to add comapny wide contacts, but fortunately this is something that could be done every few months, and isn’t particuarly honorous, there are probably existing GUI xml creation tools.

Also to note that the provisioning URL that 3CX provides contains an authentication token at the end, this is both how 3cx knows the connection is authorised and ensures that the correct MAC address matches the provisioning token. I got around this by putting an environment variable in docker compose which mapped a MAC address to the token I manually took from the 3cx provisioing url. The proxy server then appends the auth token and bobs your uncle. This was quite manual but only really needed to be done once at the beginning"

Other uses for Proxy Server

There are lots of other potential uses for a proxy server in between your VVX phones and 3CX. For example, injecting features such as the Pagination of BLF keys when using Free SMB 3CX, since it doesn’t allow for customisation of templates.