Update User Device

Update User Device #

This endpoint allows existing devices to be assigned (or removed) as softphone devices for a user for ~.UcClient.~ Desktop, Mobile & WebRTC.

Assign a Device

PUT /v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{CUSTOMER_TENANT_ID}/users/{USER_ID}/devices/pbx/{DEVICE_ID}/assign

Unassign a Device

PUT /v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{CUSTOMER_TENANT_ID}/users/{USER_ID}/devices/pbx/{DEVICE_ID}/unassign

The Body of the request needs to contain a single JSON property to indicate which type of client the device is being assigned to:

{
	"clientType": "desktop"
}

Valid clientType values:

  • desktop
  • mobile
  • webrtc
  • crm

The {DEVICE_ID} provided should be the id of the device on the communications platform, e.g. ~.pbx.kazoo.name.~.

Document note
The device being assigned as a softphone must already be assigned to the user on the communications platform.
Color Wand tip
If the device id provided is already assigned to another Client Type, assigning it again would have the effect of moving it from one client to another.

Remarks #

When assigning a softphone device to a User, ensure that the user has first been assigned the correct roles. Both of the following riles are pre-requisites to assigning a softphone device:

  • customer_user_uc
  • customer_user_uc_softphone

Example Assign #

Request # 

POST <https://api.na.myreports.cloud/api/v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{CUSTOMER_TENANT_ID}/users/{USER_ID}/devices/pbx/{DEVICE_ID}/assign> HTTP/1.1
Content-Type: application/json
accept-charges: true
Authorisation: Bearer {TOKEN}
Connection: keep-alive
{
	"clientType": "desktop"
}

Response # 

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: xx
Location: <https://api.na.myreports.cloud/api/v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{CUSTOMER_TENANT_ID}/users/{USER_ID}/devices/pbx/{DEVICE_ID}/assign>
{
	"status": "success",
	"timestamp": "2019-11-29T16:03:23.9251680Z"
}

Example Unassign #

Request # 

POST <https://api.na.myreports.cloud/api/v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{CUSTOMER_TENANT_ID}/users/{USER_ID}/devices/pbx/{DEVICE_ID}/unassign> HTTP/1.1
Content-Type: application/json
accept-charges: true
Authorisation: Bearer {TOKEN}
Connection: keep-alive

Response # 

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: xx
Location: <https://api.na.myreports.cloud/api/v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{CUSTOMER_TENANT_ID}/users/{USER_ID}/devices/pbx/{DEVICE_ID}/unassign>
{
	"status": "success",
	"timestamp": "2019-11-29T16:03:23.9251680Z"
}

Errors #

Unauthorised #

When the token is not provided, invalid or expired 

HTTP/1.1 401 Unauthorised

Bad Request #

When the provided tenant id is not in the correct format 

HTTP/1.1 400 Bad Request
Date: Thu, 06 Feb 2020 12:45:27 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 149
{
	"error": 400,
	"message": "The value '<tenant id>' is not valid.",
	"status": "error",
	"timestamp": "2020-02-06T12:45:27.5903465Z"
}

Not Found #

When there are no Customers that have a matching tenant id 

HTTP/1.1 404 Not Found
Date: Thu, 06 Feb 2020 12:46:58 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 95
{
	"error": 404,
	"message": "Not Found",
	"status": "error",
	"timestamp": "2020-02-06T12:46:58.7669535Z"
}

When the device referenced is not already assigned to the user on the communications platform. 

HTTP/1.1 404 Not Found
Date: Thu, 06 Feb 2020 12:46:58 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 95
{
	"error": 404,
	"message": "Device Not Found",
	"status": "error",
	"timestamp": "2020-02-06T12:46:58.7669535Z"
}

Payment Required #

If this request may incur any additional charges, see Charges. 

HTTP/1.1 402 Payment Required
Date: Thu, 06 Feb 2020 13:01:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 274
{
	"data": {
	"clientType": "desktop"
	},
	"error": 402,
	"message": "additional charges apply",
	"status": "error",
	"timestamp": "2020-02-06T13:01:01.1302340Z"
}