Skip to content

Commit 24f56d6

Browse files
DanielabomDanielabom
authored
Merge branch 'main' into preview-permissions-tables-update/175874
2 parents 14c576a + f8ee4b3 commit 24f56d6

File tree

2 files changed

+164
-0
lines changed

2 files changed

+164
-0
lines changed

‎concepts/namepronunciation-configure-namepronunciation-availability.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: "Manage name pronunciation settings for an organization by using the Microsoft Graph API"
3+
description: "Learn how to use Microsoft Graph APIs to enable, disable, or get settings that manage name pronunciation in an organization."
4+
author: "fondieki"
5+
ms.localizationpriority: high
6+
ms.subservice: "people"
7+
ms.custom: scenarios:getting-started
8+
ms.date: 01/05/2025
9+
---
10+
11+
# Manage pronunciation settings for an organization
12+
13+
The name pronunciation feature in Microsoft 365 allows a user to record an audio file of how their name is pronounced. With the Microsoft Graph name pronunciation API, you can enable, disable, or get settings that manage name pronunciation in an organization. For example, you can control the display within the organization of pronunciations that users create for themselves.
14+
15+
Correctly pronouncing someone's name shows inclusion and respect because names are a vital part of one's identity. By sharing how their name is pronounced, users can help others avoid making assumptions about how to address them, especially during a first interaction. In a hybrid, multicultural work or school environment, the simple act of pronouncing names correctly can help build trust and improve communication.
16+
17+
Administrators can enable or disable name pronunciation for everyone in the organization by using the Microsoft Graph API. By default, name pronunciation is disabled.
18+
19+
When name pronunciation is enabled in an an organization:
20+
21+
- Users can optionally add and manage pronunciations in the profile card in Teams and Outlook, both in desktop and on the web.
22+
- Name pronunciations appears by users' names on the profile card in Teams.
23+
- Pronunciations are only displayed internally within the organization. In multi-tenant organizations, users in all tenants can access the pronunciations provided by users in any other tenant.
24+
- Pronunciations are visible on profile cards to anyone who has an account in the organization, including guest accounts.
25+
26+
Name pronunciation data is stored in the user's mailbox. For more information, see [Data Residency for Exchange Online](/microsoft-365/enterprise/m365-dr-workload-exo?view=o365-worldwide#how-can-i-determine-customer-data-location&preserve-view=true).
27+
28+
Administrators can decide whether to display pronunciations that users set up in their profile cards. To enable the display of user-created name pronunciations, set the **isEnabledInOrganization** property of the [namePronunciationSettings](/graph/api/resources/namepronunciationsettings?view=graph-rest-beta&preserve-view=true) object to `true`. When this property is set to `true`, pronunciation is displayed for everyone within the organization. When this property is set to `false`, pronunciation not displayed for anyone within or outside the organization. The default setting is `false`.
29+
30+
> [!IMPORTANT]
31+
> When you turn name pronunciation on or off, it can take up to seven hours for users to see changes. For example, if you turn pronunciation on, users might not see the option to add recordings on their profile card for up to seven hours. If you turn pronunciation off, any previously set recording might stay visible in Microsoft 365 (for example, on profile cards) for up to seven hours.
32+
>
33+
> When an admin toggles name pronunciation off, the process of deletion is triggered, and all pronunciation data created by users starts to be deleted. Deleting name pronunciation data can take up to 30 days. If you turn pronunciation back on within that period, any recordings that existed prior to the delete signal that haven't yet been deleted from Microsoft servers will be resurfaced and become visible in Microsoft 365 experiences on the profile cards.
34+
35+
## Configure name pronunciation settings by using PowerShell
36+
37+
You can use the [Microsoft Graph PowerShell SDK](/powershell/microsoftgraph/installation) to configure name pronunciation settings in your organization.
38+
39+
### Prerequisites
40+
41+
- **PowerShell module** - Install [module version 2.3.0](https://www.powershellgallery.com/packages/Microsoft.Graph) or higher.
42+
- **.NET Framework** - Install [.NET Framework 4.7.2](https://dotnet.microsoft.com/download/dotnet-framework) or higher.
43+
44+
> [!NOTE]
45+
> The PowerShell commands for name pronunciation settings are only available in beta. Switch to the beta experience before you run the following commands.
46+
>
47+
> ```powershell
48+
> Install-Module -Name Microsoft.Graph.Beta -MinimumVersion 2.3.0
49+
> ```
50+
51+
### Review your current settings
52+
53+
To retrieve the name pronunciation configuration for an organization, use the GET method. This requires the `PeopleSettings.Read.All` permission.
54+
55+
First, create a Microsoft Graph session with the required scope and consent to the requested permissions.
56+
57+
```powershell
58+
Connect-MgGraph -Scopes "PeopleSettings.Read.All"
59+
60+
Get-MgBetaAdminPeopleNamePronunciation
61+
```
62+
63+
### Enable name pronunciation in your organization
64+
65+
By default, name pronunciations are turned off. To make name pronunciation available in your organization, update the settings using the Microsoft Graph PowerShell module.
66+
67+
First, create a Microsoft Graph session with the required permissions.
68+
69+
```powershell
70+
Connect-MgGraph -Scopes "PeopleSettings.ReadWrite.All","PeopleSettings.Read.All"
71+
```
72+
73+
After you set the permissions, use the following command, specifying `true` for the value of `-IsEnabledInOrganization`.
74+
75+
```powershell
76+
Update-MgBetaAdminPeopleNamePronunciation -IsEnabledInOrganization:$true
77+
```
78+
79+
### Disable name pronunciation in your organization
80+
81+
Alternatively, you can make name pronunciation unavailable for your organization by using the following command. Specify `false` for the value of `-IsEnabledInOrganization`.
82+
83+
```powershell
84+
Get-MgBetaAdminPeopleNamePronunciation -IsEnabledInOrganization:$false
85+
```
86+
87+
## Configure name pronunciation settings by using the Microsoft Graph REST API
88+
89+
You can use the [namePronunciationSettings](/graph/api/resources/namepronunciationsettings?view=graph-rest-beta&preserve-view=true) resource and its associated methods to configure name pronunciation settings in your organization.
90+
91+
### Confirm your current name pronunciation settings
92+
93+
The [Get namePronunciationSettings](/graph/api/namepronunciationsettings-get?view=graph-rest-beta&preserve-view=true) API returns the current settings for name pronunciation in your organization.
94+
95+
Use the following HTTP request to retrieve all current settings, including those with name pronunciation disabled.
96+
97+
``` http
98+
GET https://graph.microsoft.com/v1.0/admin/people/namePronunciation
99+
```
100+
101+
If successful, a `200 OK` response code is returned with a [namePronunciationSettings](/graph/api/namepronunciationsettings-get?view=graph-rest-beta&preserve-view=true) object in the response body, as shown in the following example response.
102+
103+
``` http
104+
HTTP/1.1 200 OK
105+
Content-Type: application/json
106+
107+
{
108+
"isEnabledInOrganization": false
109+
}
110+
```
111+
112+
### Enable name pronunciation in your organization
113+
114+
Setting the **isEnabledInOrganization** property of the **namePronunciationSettings** object to `true` enables name pronunciation in your organization.
115+
116+
Use the [Update namePronunciationSettings](/graph/api/namepronunciationsettings-update?view=graph-rest-beta&preserve-view=true) method to enable name pronunciation, as shown in the following example:
117+
118+
``` http
119+
PATCH https://graph.microsoft.com/v1.0/admin/people/namePronunciation
120+
Content-Type: application/json
121+
122+
{
123+
"isEnabledInOrganization": true
124+
}
125+
```
126+
127+
If successful, a `200 OK` response code is returned with a [namePronunciationSettings](/graph/api/resources/namepronunciationsettings?view=graph-rest-beta&preserve-view=true) object in the response body, as shown in the following example response.
128+
129+
``` http
130+
HTTP/1.1 200 OK
131+
Content-Type: application/json
132+
133+
{
134+
"isEnabledInOrganization": true
135+
}
136+
```
137+
138+
### Disable name pronunciation in your organization
139+
140+
Setting the **isEnabledInOrganization** property of the **namePronunciationSettings** resource to `false` makes name pronunciation unavailable in your organization.
141+
142+
Use the [Update namePronunciationSettings](/graph/api/namepronunciationsettings-update?view=graph-rest-beta&preserve-view=true) method to disable name pronunciation, as shown in the following example.
143+
144+
``` http
145+
PATCH https://graph.microsoft.com/v1.0/admin/people/namePronunciation
146+
Content-Type: application/json
147+
148+
{
149+
"isEnabledInOrganization": false
150+
}
151+
```
152+
153+
If successful, a `200 OK` response code is returned with a [namePronunciationSettings](/graph/api/resources/namepronunciationsettings?view=graph-rest-beta&preserve-view=true) object in the response body, as shown in the following example response.
154+
155+
``` http
156+
HTTP/1.1 200 OK
157+
Content-Type: application/json
158+
159+
{
160+
"isEnabledInOrganization": false
161+
}
162+
```

‎concepts/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -778,6 +778,8 @@ items:
778778
href: add-properties-profilecard.md
779779
- name: Enable or disable pronouns
780780
href: pronouns-configure-pronouns-availability.md
781+
- name: Enable or disable name pronunciation
782+
href: namepronunciation-configure-namepronunciation-availability.md
781783
- name: Item insights overview
782784
href: item-insights-overview.md
783785
- name: People insights overview

0 commit comments

Comments
 (0)