How to Push a Company Phonebook to Yealink Desk Phones Automatically

By John Rowlinson

If your office uses Yealink desk phones, you can have the handsets look up callers in your own customer and supplier list without typing contacts into each phone. The feature is called the remote phonebook. The phones fetch a file from a server you control, so once it is set up there is little to do beyond checking it keeps running.

Why a central phonebook helps

I use Yealink handsets in my own office, and this is how we do it. Our own system creates an XML phonebook and publishes it to an internal web page, and the Yealink handsets fetch it every hour and update themselves. When a customer rings, their name is on the screen before anyone picks up.

Importing contacts into each phone works at first, but every new customer or changed number then means updating each handset, and the phones soon drift apart. A remote phonebook has one source, so a change made once reaches every desk at the next refresh.

If a hosted provider manages your phones, check what they allow. Many support central directories or CRM links. Some lock the handsets, which leaves you with whatever directory they offer and possibly two lists to maintain. Publishing your own file keeps the data with you and uses standard Yealink settings.

The phonebook file

The remote phonebook is a simple XML file served from a web page. This is the format we use: a YealinkIPPhoneDirectory containing one DirectoryEntry per contact, each with a Name and a Telephone. We put the person and their company together in the name, so the screen shows exactly who is calling. Here is an example with two fictional entries:

<?xml version="1.0" encoding="UTF-8"?>
<YealinkIPPhoneDirectory>
  <DirectoryEntry>
    <Name>Sarah Holt (Harbour Bakery)</Name>
    <Telephone>01632960123</Telephone>
  </DirectoryEntry>
  <DirectoryEntry>
    <Name>Tom Price (Price &amp; Sons Ltd)</Name>
    <Telephone>01632960456</Telephone>
  </DirectoryEntry>
</YealinkIPPhoneDirectory>

Add one DirectoryEntry block for each number. The ampersand in "Price & Sons" is written as & because a bare ampersand is not valid XML and can stop the whole file loading. Angle brackets in names need the same treatment. Yealink also supports a newer format with menus for grouping contacts; check the administrator guide for your model if you want separate Customers and Suppliers lists.

Formats, limits and defaults differ between models and firmware, so check the Yealink administrator guide for your exact model and firmware version before building anything. The details here come from Yealink's guides for the T2, T4 and T5 series.

Generating and publishing the file

A small script or scheduled export from your CRM, accounts package or database can write the file to a web server on your internal network. A few safeguards help:

• Use an XML library to build the file, so special characters are escaped for you. One bad character can stop the whole file loading.
• Validate, then publish in one step. Write to a temporary file, check it, then swap it into place, so a phone never fetches a half-written file. If generation fails, keep the last valid version.
• Use one consistent number format. The phone compares the caller ID with the numbers in the file. Look at a few real incoming calls to see whether numbers arrive as 01632 style or with +44, and match that, without spaces.
• Check the handset's directory limits in your guide before exporting a large CRM.

Remember there are two schedules: your export and each handset's refresh. Changes and deletions are not instant. Add a simple check that alerts you if the export fails or the file stops being downloaded.

The file is effectively your customer list. Export only the names and business numbers staff need. Names of individuals and direct or mobile numbers can be personal data under UK GDPR, so you need a lawful basis, suitable privacy information, restricted access and a habit of removing old contacts. The ICO's guidance for small businesses explains this. Restrict access to the server to the phones' network, and use HTTPS where your phones support it, with a username and password as appropriate. A password alone does not make an internet-facing file safe. The NCSC's Small Business Guide covers the basics.

How we protect ours. Our phonebook sits on a web server rather than inside the office, so we lock it down three ways. The file has a long random name that nobody could guess, something like pb_ followed by 32 random letters and numbers. The server asks for a username and password, which go into the phone's remote phonebook settings alongside the address, and it only keeps a scrambled copy of the password that cannot be turned back into the real one. And it only answers requests from our own internet connections: the office and home. Anyone else gets "Forbidden", even with the right address and password, and that includes one of our own phones plugged in on another network. That last point is worth knowing before someone takes a desk phone home and wonders why the names have gone.

Your situation may be slightly different. ask a question below ↓ and our editorial team will reply with our advice.

Configuring the phones

These provisioning parameters can go in a configuration file, or be set in the phone's web interface under Directory, then Remote Phone Book (menu names vary by firmware). This example uses plain HTTP on an isolated internal network; prefer HTTPS where supported.

features.remote_phonebook.enable = 1
remote_phonebook.data.1.url = http://192.168.1.10/phonebook.xml
remote_phonebook.data.1.name = Company Phonebook
features.remote_phonebook.flash_time = 3600

• remote_phonebook.data.1.url is the file's address. Several phonebooks can be numbered from 1; the maximum varies by model.
• remote_phonebook.data.1.name is the name shown on the phone.
• features.remote_phonebook.enable = 1 makes the phone look up the remote phonebook on incoming and outgoing calls and show the matched name. The default is 0. Without it, remote-phonebook name matching is disabled; names supplied by your phone system may still appear.
• features.remote_phonebook.flash_time = 3600 refreshes the cached copy hourly. In the guides above the range is 3600 to 1296000 seconds, the default 21600 (six hours), and 0 stops refreshing.

If a phone system such as 3CX provisions your phones, first check whether it already supplies a directory and whether your provider allows customisation. Settings made only on the handset may be overwritten when the phone reprovisions; users on the 3CX forum have reported settings reverting after a reboot. Use the method your phone system's documentation supports for your version, as editing a stock template can be undone by updates.

Testing and troubleshooting

1. Add your mobile number as a test entry and publish the file.
2. Reboot a phone or wait for the refresh.
3. Open the remote phonebook on the handset and check entries appear. This confirms the file loaded.
4. Ring the desk phone from your mobile and check your name shows. This confirms matching works.
5. Check a real customer's call too, and dial out from the directory.
6. Remove the test entry.

If the directory will not load, open the file in a web browser, which usually points out XML faults. Then confirm the server is reachable from the phones' network or VLAN, not just your computer, and check the server's access logs for the handset's request. With HTTPS, make sure the phone trusts the certificate and its clock is correct.

If the directory loads but names do not appear on calls, compare the caller ID on screen with the number in your file, character by character.

One caution for staff: a name on the screen is not proof of who is calling, because caller ID can be spoofed. Ofcom's website explains more.

After that, keep an eye on your export and refresh checks, and tidy the source list now and then.