Microsoft Teams is more than just a collaboration tool. It can also provide telephone services, so your users can make and receive phone calls. Another feature included in the Phone System license is using voice apps such as auto attendants and call queues. The auto attendant provides a menu system for incoming calls and includes a directory search option. I'll cover configuration of this option below.
Latest posts by Jeff Brown (see all)

The Microsoft Teams auto attendant has lots of great features: customized greetings, after-hours and holiday call handling, and a menu system to direct calls to different departments (think Press 1 to speak with Sales).

Another great feature is the directory search. This allows the caller to search your directory by name or extension to connect with that person. This eliminates the need for someone to answer the call and perform the transfer manually. However, configuring this option is not completely intuitive. Let's jump into the auto attendant and view its configuration.

Configuring voice input

The first setting we are going to examine is in the General info section of the auto attendant. Here, we can configure the language and voice inputs. This enables speech recognition in the selected language so the caller can make menu selections using their voice. Enabling this setting also allows callers to search the directory by saying a person's name.

Enabling voice inputs

Enabling voice inputs

If this setting is not enabled, then callers need to select menu choices using their keypad. To search the directory, callers will need to type in the person's first or last name using the keypad. For example, to search for "Jeff" on the keypad, the caller would type "5333."

Call flow settings

The next section in the auto attendant is for Call flow settings. This is where you can design the menu system for callers to traverse. When users select an option through a dial key or voice input, the options for redirection include:

  • Operator (defined on the General info page)
  • A person in the organization
  • Voice app, like an auto attendant or a call queue
  • Voicemail
  • External phone number

The star key (*) is reserved for repeating the message, and the pound key (#) is reserved for going back to the previous menu. Be sure to include these as options in the greeting if they are applicable.

After the menu options, we can configure the directory search. We can disable it or configure dial-by-name or dial-by-extension. If dial-by-name is selected and voice inputs are enabled, then the caller can either say the name or enter it on the keypad. If voice inputs are disabled, then the caller can only enter the name using the keypad. The last option is to dial the person by their defined extension using only the keypad.

Menu system and directory search settings

Menu system and directory search settings

If you're like me, at this point you might be wondering how we let the caller know about the directory search option. There's no redirect option for a dial key, and no additional settings after enabling directory search. Microsoft's documentation only states that the caller can say the person's name or enter their extension.

While it's obvious now, the solution wasn't when I first encountered this. The solution is to modify the text-to-speech to include instructions that the caller can search the directory by name (by voice or keypad) or enter the extension (if a recorded greeting is used, the instructions are included there). Looking back at the previous screenshot, the text only includes the menu system options. Let's modify it to include instructions for searching the directory.

Updated greeting with instructions for directory search

Updated greeting with instructions for directory search

The instructions should match the options we have configured. If we don't have voice inputs enabled, then only mention the dial-by-keypad functionality. The same is true for dialing by extension.

One caveat: if searching by entering the name on the keypad, only enter the first OR last name, not both. If there are multiple matches for the name, the system will list the matching users. If the caller wants to exit the directory search, they can press the pound key (#).

Dialing by extension

Dialing by extension requires some additional configuration. If you have previous experience with Lync or Skype for Business Server, administrators configured extensions in the account LineURI in the format "+<phonenumber>;ext=<extension>."

This is not supported in Microsoft Teams. Instead, we configure properties directly on the Active Directory user account (whether synced from on-premises or Azure Active Directory). The extension is specified as part of these phone attributes:

  • HomePhone
  • Mobile/MobilePhone
  • TelephoneNumber/PhoneNumber
  • OtherTelephone

If you are using the Microsoft Online PowerShell module (MSOnline), the user attributes are "PhoneNumber" and "MobilePhone." If you are using the Azure Active Directory PowerShell module (AzureAD), the attributes are "TelephoneNumber" and "Mobile."

We configure the extension in one of the following formats:

  • +<phonenumber>;ext=<extension>
  • x<extension>

Here are a couple of PowerShell samples using commands from both the MSOnline and Azure AD PowerShell modules:

# Full phone number with extension
Set-MsolUser -UserPrincipalName  -PhoneNumber "+15551234567x567"

Set-AzureADUser -ObjectId  -TelephoneNumber "+1555

# Just the extension
Set-AzureADUser -ObjectId  -TelephoneNumber "x567"

Set-MsolUser -UserPrincipalName  -PhoneNumber "x567"

It can take up to twelve hours for the changes to the Azure Active Directory properties "PhoneNumber" and "MobilePhone" to be available for dialing. You can also set these values on the user properties page in the Microsoft 365 admin center:

Configuring phone number extension

Configuring phone number extension

One final thing to note on these extensions: they do not configure extension dialing for users inside the organization. This is strictly for dialing by extension inside an auto attendant. If you want to configure extension dialing for users inside the organization, you will need to configure dial plans with normalization rules. To read more about this, check out this article, What are dial plans?, from Microsoft Docs.

Combining directory search and extension dialing

We can enable both directory search and extension dialing using multiple auto attendants. One auto attendant's directory search is configured with dial-by-name while another is configured with dial-by-extension. In the primary auto attendant, we would add two dial key menu options for each search option and select the auto attendant as the key's destination.

Limiting directory search

Finally, we can also limit the directory search to specific people in the organization by setting the dial scope. You may not want executives or other specific individuals to be reachable through a public telephone number. The dial scope only applies if the dial by name directory search option is configured. It does not apply if dial by extension is enabled, as all users with an extension configured will be available for targeting.

In the dial scope section, there is an Include and Exclude section. You could enable all online users as targets for directory search, then exclude specific people or groups by entering the relevant user or group names. Alternatively, you can limit the directory search by specifying the relevant users or groups.

Limiting directory search with dial scope

Limiting directory search with dial scope


For additional reading on auto attendants, check out these resources:

Microsoft Docs: Set up a Cloud auto attendant

Microsoft Docs: Small business example – Set up an Auto Attendant

Subscribe to 4sysops newsletter!

Questions on configuring Microsoft Teams voice applications? Drop me a note below or find me on Twitter or LinkedIn to discuss further.

  1. Guest 3 years ago

    In the code this is not OK:

    Set-MsolUser -UserPrincipalName <UserPrincipalName> -PhoneNumber "+15551234567x567"

    This is OK

    Set-MsolUser -UserPrincipalName <UserPrincipalName> -PhoneNumber "+15551234567;ext=567"

  2. Guest 3 years ago

    Hello Jeff,

    In my original testing the x<extension> work but +<phonenumber>x<extension> did not worked. We had to convert all users phone field to +<phonenumber>;ext=<extension>. 

    MS changed the page and made it less perfect: see cached version:

    Where it stated : 

    • The required format to enter the extension in the user phone number field is either +<phonenumber>;ext=<extension> or x<extension>.

    I'll do some testing calling an AA to see if the +<phonenumber>x<extension> find the extension.

    Thanks and regards,

    • Guest 3 years ago

      After testing this is now working : +<phonenumber>x<extension>

      In our case the original was ???-???-????x<extension> (no plus) this is still not working. We had to rush the change in Feburay for the AA migration from Exchange to Teams. So we switched to the official e.164 model of +<phonenumber>;ext=<extension> to prevent future issue.

      So your examples works, sorry about that. MS seams to be more flexible now.

      Thanks and regards,

  3. Thang Nguyen 3 years ago


    Is it possible for the Teams Users to call the AA or CQ like the internal calls via the Sip address of the Resource Account which assigned for the AA or CQ ?

    Thank you in advance.


    • Author
      Jeff Brown (Rank 2) 3 years ago

      Yes they should be able to. The user should search for the name of the resource account and be able to call it like a normal user.

      • Thang Nguyen 3 years ago

        Hello Jeff Brown,

        I did check and test, but the Team user could not find the Address or name of the resource accounts in the search box.

        Info of the Team user which I used for testing:

        – Homed O365 (moved from SFB on-prem)

        – Teams Only mode

        – Licensed: Office 365 E3 

        Can you advise more on this?  

        Do I need to enable/configure other things for the AA&CQ or the Teams user?

        Thank you.


  4. Thang Nguyen 3 years ago

    Hello Jeff Brown,

    I did check and test, but the Team user could not find the Address or name of the resource accounts in the search box.

    Info of the Team user which I used for testing:

    – Homed O365 (moved from SFB on-prem)

    – Teams Only mode

    – Licensed: Office 365 E3 

    Can you advise more on this?  

    Do I need to enable/configure other things for the AA&CQ or the Teams user?

    Thank you.


  5. Teams admin IN 2 years ago

    Jeff, firstly thank you this very useful article. Does the extension have to be unique for the user across the tenant ? 

    • Author
      Jeff Brown (Rank 2) 2 years ago

      If you are assigning the number on the user account in the M365 portal, no, it doesn't have to be unique. But I am unsure how Teams would handle trying to transfer the call. I've never tried that scenario.

      Right now Teams (as far as I know) doesn't support settings extensions like it did back in the Skype for Business Server days. My guess is for right now is to avoid using the same extension for multiple users.

  6. Mike Gereg 2 years ago

    Kinda of a similar question as above…Any idea how to handle multiple people in the directory with the same name in the voice directory search? Right now it just states the similar names twice which doesn’t really help. Was hoping it would state department or location but I can’t figure out a way to add more info.

    • Author
      Jeff Brown (Rank 2) 2 years ago

      I have not tested this but maybe changing the display name for the users? I’ve seen where companies do something like “Jane Doe (Sales)” to distinguish between people with the same names.

  7. mehrdad 1 year ago

    Hi Jeff, thanks for the article.
    I am trying to add nicknames to the dial by name directory. For example, Leonardo goes by Lenny so when people call and say “Lenny”, the system doesn’t find him. I have added Lenny to the middle name, display name and other places but the system still doesn’t recognize a “Lenny”. The name Lenny even shows up in the Teams\Users\Manage Users section. Any ideas?

    • Mehrdad 1 year ago

      Just tested and it works now…needed to give it roughly 24 hours for the AD name to make its way to the voice prompt search index.

  8. RJ 1 year ago

    Thanks very much for this great info! Helped me a bunch!

  9. Gabriel Wishnu 11 months ago

    Hi Jeff,

    When Dialing by extension is chosen, how do we avoid the system to read the full name of the ext owner? Some company want to prevent the system not to read names or even better to disable the announcement but sill want to be reached by exts.

Leave a reply to mehrdad Click here to cancel the reply

Please enclose code in pre tags

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2023


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account