Set-CsPhoneNumberAssignment

Module:

MicrosoftTeamsPowerShell

Applies to:

Microsoft Teams

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. This example is only applicable for Direct Routing phone numbers.

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.

Related Links

• Remove-CsPhoneNumberAssignment
• Get-CsPhoneNumberAssignment