Set-CsPhoneNumberAssignment
This cmdlet will assign a phone number to a user or a resource account (online application instance).
Syntax
Set-CsPhoneNumberAssignment
-PhoneNumber <string>
-LocationId <string>
[<CommonParameters>]
Set-CsPhoneNumberAssignment
-PhoneNumber <string>
-NetworkSiteId <string>
[<CommonParameters>]
Set-CsPhoneNumberAssignment
-Identity <String>
-PhoneNumber <String>
-PhoneNumberType <String>
[-LocationId <String>]
[-NetworkSiteId <string>]
[-AssignmentCategory <string>]
[<CommonParameters>]
Set-CsPhoneNumberAssignment
-Identity <String>
-EnterpriseVoiceEnabled <Boolean>
[<CommonParameters>]
Set-CsPhoneNumberAssignment
-PhoneNumber <string>
-ReverseNumberLookup <string>
[<CommonParameters>]
Description
This cmdlet assigns a phone number to a user or resource account. When you assign a phone number the EnterpriseVoiceEnabled flag is automatically set to True.
You can also assign a location to a phone number.
To remove a phone number from a user or resource account, use the Remove-CsPhoneNumberAssignment cmdlet.
Examples
Example 1
Set-CsPhoneNumberAssignment -Identity user1@contoso.com -PhoneNumber +12065551234 -PhoneNumberType CallingPlan
This example assigns the Microsoft Calling Plan phone number +1 (206) 555-1234 to the user user1@contoso.com.
Example 2
$loc=Get-CsOnlineLisLocation -City Vancouver
Set-CsPhoneNumberAssignment -Identity user2@contoso.com -PhoneNumber +12065551224 -PhoneNumberType CallingPlan -LocationId $loc.LocationId
This example finds the emergency location defined for the corporate location Vancouver and assigns the Microsoft Calling Plan phone number +1 (206) 555-1224 and location to the user user2@contoso.com.
Example 3
Set-CsPhoneNumberAssignment -Identity user3@contoso.com -EnterpriseVoiceEnabled $true
This example sets the EnterpriseVoiceEnabled flag on the user user3@contoso.com.
Example 4
Set-CsPhoneNumberAssignment -Identity user3@contoso.com -LocationId 'null' -PhoneNumber +12065551226 -PhoneNumberType OperatorConnect
This example removes the emergency location from the phone number for user user3@contoso.com.
Example 5
Set-CsPhoneNumberAssignment -Identity cq1@contoso.com -PhoneNumber +14255551225 -PhoneNumberType DirectRouting
This example assigns the Direct Routing phone number +1 (425) 555-1225 to the resource account cq1@contoso.com.
Example 6
Set-CsPhoneNumberAssignment -Identity user4@contoso.com -PhoneNumber "+14255551000;ext=1234" -PhoneNumberType DirectRouting
This example assigns the Direct Routing phone number +1 (425) 555-1000;ext=1234 to the user user4@contoso.com.
Example 7
Try { Set-CsPhoneNumberAssignment -Identity user5@contoso.com -PhoneNumber "+14255551000;ext=1234" -PhoneNumberType DirectRouting -ErrorAction Stop } Catch { Write-Host An error occurred }
This example shows how to use Try/Catch and ErrorAction to perform error checking on the assignment cmdlet failing.
Example 8
$TempUser = "tempuser@contoso.com"
$OldLoc=Get-CsOnlineLisLocation -City Vancouver
$NewLoc=Get-CsOnlineLisLocation -City Seattle
$Numbers=Get-CsPhoneNumberAssignment -LocationId $OldLoc.LocationId -PstnAssignmentStatus Unassigned -NumberType CallingPlan -CapabilitiesContain UserAssignment
foreach ($No in $Numbers) {
Set-CsPhoneNumberAssignment -Identity $TempUser -PhoneNumberType CallingPlan -PhoneNumber $No.TelephoneNumber -LocationId $NewLoc.LocationId
Remove-CsPhoneNumberAssignment -Identity $TempUser -PhoneNumberType CallingPlan -PhoneNumber $No.TelephoneNumber
}
This example shows how to change the location for unassigned Calling Plan subscriber phone numbers by looping through all the phone numbers, assigning each phone number temporarily with the new location to a user, and then unassigning the phone number again from the user.
Example 9
$loc=Get-CsOnlineLisLocation -City Toronto
Set-CsPhoneNumberAssignment -PhoneNumber +12065551224 -LocationId $loc.LocationId
This example shows how to set the location on a phone number.
Example 10
$OldLocationId = "7fda0c0b-6a3d-48b8-854b-3fbe9dcf6513"
$NewLocationId = "951fac72-955e-4734-ab74-cc4c0f761c0b"
# Get all phone numbers in old location
$pns = Get-CsPhoneNumberAssignment -LocationId $OldLocationId
Write-Host $pns.count numbers found in old location $OldLocationId
# Move all those phone numbers to the new location
foreach ($pn in $pns) {
Try {
Set-CsPhoneNumberAssignment -PhoneNumber $pn.TelephoneNumber -LocationId $NewLocationId -ErrorAction Stop
Write-Host $pn.TelephoneNumber was updated to have location $NewLocationId
}
Catch {
Write-Host Could not update $pn.TelephoneNumber with location $NewLocationId
}
}
Write-Host (Get-CsPhoneNumberAssignment -LocationId $OldLocationId).Count numbers found in old location $OldLocationId
Write-Host (Get-CsPhoneNumberAssignment -LocationId $NewLocationId).Count numbers found in new location $NewLocationId
This Example shows how to update the LocationID from an old location to a new location for a set of phone numbers.
Example 11
Set-CsPhoneNumberAssignment -Identity user3@contoso.com -PhoneNumber +12065551226 -ReverseNumberLookup 'SkipInternalVoip'
This example shows how to turn off reverse number lookup (RNL) on a phone number. When RNL is set to 'SkipInternalVoip', an internal call to this phone number will not attempt to pass through internal VoIP via reverse number lookup in Microsoft Teams. Instead the call will be established through external PSTN connectivity directly.
Parameters
-AssignmentCategory
This parameter is reserved for internal Microsoft use.
Type: | System.String |
Position: | named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Applies to: | Microsoft Teams |
-EnterpriseVoiceEnabled
Flag indicating if the user or resource account should be EnterpriseVoiceEnabled.
This parameter is mutual exclusive with PhoneNumber.
Type: | System.Boolean |
Position: | named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Applies to: | Microsoft Teams |
-Identity
The Identity of the specific user or resource account. Can be specified using the value in the ObjectId, the SipProxyAddress, or the UserPrincipalName attribute of the user or resource account.
Type: | System.String |
Position: | named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-LocationId
The LocationId of the location to assign to the specific user. You can get it using Get-CsOnlineLisLocation. You can set the location on both assigned and unassigned phone numbers.
Removal of location from a phone number is supported for Direct Routing numbers and Operator Connect numbers that are not managed by the Service Desk. If you want to remove the location, use the string value null for LocationId.
Type: | System.String |
Position: | named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NetworkSiteId
This parameter is reserved for internal Microsoft use.
Type: | System.String |
Position: | named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Applies to: | Microsoft Teams |
-PhoneNumber
The phone number to assign to the user or resource account. Supports E.164 format like +12065551234 and non-E.164 format like 12065551234. The phone number can't have "tel:" prefixed.
We support Direct Routing numbers with extensions using the formats +1206555000;ext=1234 or 1206555000;ext=1234 assigned to a user or resource account.
Setting a phone number will automatically set EnterpriseVoiceEnabled to True.
Type: | System.String |
Position: | named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PhoneNumberType
The type of phone number to assign to the user or resource account. The supported values are DirectRouting, CallingPlan, and OperatorConnect. When you acquire a phone number you will typically know which type it is.
Type: | System.String |
Position: | named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
None
Outputs
System.Object
Notes
The cmdlet is available in Teams PowerShell module 3.0.0 or later. The parameter set LocationUpdate was introduced in Teams PowerShell module 5.3.1-preview. The parameter NetworkSiteId was introduced in Teams PowerShell module 5.5.0. The parameter set NetworkSiteUpdate was introduced in Teams PowerShell module 5.5.1-preview.
The cmdlet is only available in commercial and GCC cloud instances.
If a user or resource account has a phone number set in Active Directory on-premises and synched into Microsoft 365, you can't use Set-CsPhoneNumberAssignment to set the phone number. You will have to clear the phone number from the on-premises Active Directory and let that change sync into Microsoft 365 first.
The previous command for assigning phone numbers to users Set-CsUser had the parameter HostedVoiceMail. Setting HostedVoiceMail for Microsoft Teams users is no longer necessary and that is why the parameter is not available on Set-CsPhoneNumberAssignment.