This week I took a deep dive investigation into how Microsoft Teams handles Contacts. The background to this was that a customer couldn’t work out why some of their colleagues where showing with incorrect job titles or phone numbers. Rather than describe their issue, this article looks into the different behaviour of contacts and contact cards.
First Rule of Contacts
A ‘Contact’ is not an address in your Exchange Global Address List. A Contact is an object stored in one of two locations:
- A Local Object stored in your Teams database
- A Local Contact stored in your Outlook / Mailbox (all local lists)
A Contact can be saved FROM the Global Address List into either of these two location above.
Second Rule of Contacts
A Contact’s information can be enriched from multiple locations. Teams initially does a match on ‘e-mail’ address using the following logic:
If e-mail address matches a user in the Global Address List, it will attempt to retrieve the following data from the contact’s Mailbox information:
- Picture
- Job Title
- Mobile Phone Number
- Work Phone Number
- IM Address
And will add this as a record to your contact list.
EXCEPT
If the same e-mail address is found in your local contacts in your Outlook / Mailbox contacts directories. If it finds a match with a local contact, then the contact information is augmented using both sources in the following precedence:
- The Outlook Contact Local Fields will always take precedence over the same information
- Where an Outlook Contact exists, any missing information will not be populated from the GAL account object, except for the person’s job title.
Third Rule – Local Contacts Can Break Teams
If you do have a local contact in your mailbox contact list, then you must ensure that it is factually correct with at least the following information
- Work Email Address
- IM Address
If you do not have an IM Address listed in the local contact, then Teams will not be able to use the contact for video, chat or e-mail action buttons
Similarly their contact card hover will be missing all of the controls to quickly contact them
Adding the IM address displays the action buttons and populates the contact card
And in Teams this is reflected as:
Phone numbers are not listed in the hover card when populated from Outlook local contacts. However, they are populated as a drop down on the contact object in. Calling / Contacts
Number Handling
Local contacts also allow phone numbers to be added. By default, Teams will display the ‘Work Mobile’ local contact field first in the contact list table
If the mobile field is not populated, the ‘Work phone’ local field is used. Home Phone is used in the call drop down if populated.
Additional Mobiles, Work or Home Phone fields are not used. e.g. ‘Home Phone 1’.
Formatting Issues Break Calling
As you can see in the above examples, the number formats used are not in E.164 format. This is to simulate the input of how people can add phone numbers to local contacts. It is something that IT cannot control. Numbers entered in non-conforming standards will fail dial plan normalization and call routing.
To combat this, IT need to understand how local contact numbers are populated and adapt the Teams Dial Plan to normalize them to conforming formats for successful call routing.
To understand what people have stored in their local contacts, admins can run an extract script using EWS by David Barrett
Numbers Don’t Show On Hover Card
Numbers populated from local contact fields do not get populated into the hover card. This is the same for job title.
Search
In Teams you have the ability to use the search bar to search for internal contacts from the GAL. In the situation where you have a person listed in your local contacts with a local job title, the search will return the job title found in the GAL, not your contact.
Summary
Local contacts for internal colleagues is bad if augmented with localised field population. Unless the contact owner is going to ensure that the contact fields are correctly and fully completed, they are going to have a negative experience and it will impact their ability to communicate.
Fixing It
Teams is built to use the information found in the Cloud, not for localised and siloed information. Generally speaking local contacts are fine for external contacts, but for internal colleagues they should only be used when the information used to enrich them can be correctly obtained from the GAL.
Cloud Only Tenants
For tenants that are cloud only, meaning no On-Prem AzureAD contact information can be written in one of two locations.
- Exchange Online Mailbox Contact Information
- AzureAD User Object Contact Information
There is bidirectional sync between these locations so that if you do modify a field in either admin center, the information is synchronised between them.
Synched Tenants
For tenants with on-prem AD and AzureAD Connect synchronisation, then the source of truth is always on-prem AD.
Admins must ensure that the contact information in User Object, namely:
- telephoneNumber
- mobile
- homePhone
- title (job title)
is correct and in a format that the Teams Dial Plan can support. For consistency and simplicity, I recommend E.164 format because that means that it is Dial Plan independent and can go straight to call routing.
All other phone attributes including ipPhone can be synched, but are not used by Teams.
Gotchas
In cases where incorrect information has been synched from on-prem during initial synchronisation, changing the phone number fields in AD doesn’t always update the user’s AzureAD object or Exchange Contact Information. I have observed Delta sync not sending these changes.
Therefore, it is always good to perform a full initial sync at least once a week to ensure directories can be properly maintained.
If you use Teams Direct Routing the Line URI you assign does not automatically show in the user’s contact hover card. You will need to write this into the AD Object or AzureAD manually or by process.
The Teams Delay
Once changes have been made to the contact’s user object do not expect Teams to pick this change up any time soon. Observations I have made is that this can take anything from 24 to 72 hours to appear in the Teams client.
Finally, if you want the hover card to show perfectly, then the information must be correct in the Exchange contact information on the target user’s mailbox. It will never show right where the same user is a local contact in your Outlook personal contacts list.
