Update a device name

Tool Name: airdroid_business_update_device_name

Risk Level: 🟠 Medium Risk

Execution Mode: ⚡ Synchronous

Category: Device Management

Quick Start (Copy & Use)

Summary: Update a device's display name.

Prerequisites: DeviceId (device ID) + DeviceName (new device name).

Success Criteria: StatusCode == 200 and ErrorMessage is empty string.

What to Do Next: Use Get a Device by Name to verify the name has been updated.

Minimal Request Example:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "DeviceName": "Sales-Tablet-001"
}

Minimal Response Example:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Set a Standardized Name

When to use: Rename a device according to company naming conventions.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "DeviceName": "BJ-Sales-Tablet-001"
}

Recipe 2: Add Location Identifier

When to use: Add location information to the device name.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "DeviceName": "Lobby-Kiosk-Floor1"
}

Recipe 3: Batch Rename (Requires Loop Calls)

When to use: Rename multiple devices in batch.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "DeviceName": "Device-2024-001"
}

Note: This tool can only update one device at a time; batch renaming requires loop calls.

1. Overview

1.1 Description

Update the display name of a specified device. The device name is used to identify the device in the AirDroid Business management console.

1.2 When to Use

• New device onboarded and needs a standardized name
• Device usage has changed and the name needs to reflect the new purpose
• Standardize device names according to company naming conventions

1.3 Execution Mode and Response

This operation is synchronous and returns results immediately.

1.4 Prerequisites

1.5 Prerequisite Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceId`

Device unique identifier.

• Type: string
• Format: Non-empty string
• Source:

How to obtain:

1. Via Get All Devices tool - use the device_id field from the response
2. Via Get a Device by Name tool - exact name query

The device_id field from the output can be used directly as this parameter.

• Example:

  "fa6edcff65ab444e8b5e0eb08df4175d"

`DeviceName`

New device display name.

• Type: string
• Format:
  • Cannot be empty
  • Maximum length: 40 characters
  • Special characters not allowed: / \ : * < > | ? ' " = ; , &
• Notes:
  • Device names can be duplicated (different devices can have the same name)
  • It is recommended to use a meaningful naming convention (e.g., department-type-number)
• Example:

  "Sales-Tablet-001"

  "NYC-Lobby-Kiosk"

2.3 Parameter Combination Logic

• Both parameters are required
• DeviceName completely replaces the original name

3. Outputs

3.1 Response Example

Success response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response:

{
  "StatusCode": -1,
  "ErrorMessage": "Invalid device_id."
}

3.2 Field Descriptions

4. Examples

4.1 Basic Example: Update Device Name

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "DeviceName": "Sales-Tablet-001"
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Use Standardized Naming

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "DeviceName": "BJ-HQ-Floor3-Meeting-Room-A"
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.3 Error Example: Name Contains Invalid Characters

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "DeviceName": "Sales/Marketing Device"
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": "Device name contains invalid characters"
}

5. Error Handling

5.1 AB Three-Layer Error Codes

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Single device operation: This tool can only update one device at a time; batch renaming requires loop calls
• Verify update: After updating, use Get a Device by Name to verify the name has taken effect

6.2 Security Considerations

🟡 Write operation:

• Full replacement: The new name completely replaces the original name
• Confirm target: Verify DeviceId is correct before updating
• Naming convention: It is recommended to use a consistent naming convention for easier management

6.3 Idempotency

This operation is naturally idempotent. Multiple calls with the same DeviceName have no side effects; the device name remains unchanged.

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tool Comparison

8. Tool Chains

8.1 Find by Old Name and Rename

Scenario: You know the device's old name and need to update it to a new name.

Tool Chain:

Get a Device by Name → Update a Device Name

Steps:

1. Call Get a Device by Name to get the device's DeviceId
2. Use the returned DeviceId to call Update a Device Name

8.2 Batch Device Rename

Scenario: Rename multiple devices according to rules.

Tool Chain:

Get All Devices → [Loop] Update a Device Name

Steps:

1. Call Get All Devices to get the device list
2. Iterate through the device list and generate new names for each device
3. Call Update a Device Name for each device

8.3 Rename and Verify

Scenario: Update the name and confirm the operation succeeded.

Tool Chain:

Update a Device Name → Get a Device by Name (verify)

Steps:

1. Call Update a Device Name to update the name
2. Confirm ErrorMessage is empty
3. Call Get a Device by Name using the new name to confirm the device exists

Appendix Reference:

• Field Reference: https://www.goinsight.ai/tools/field-reference/
• Error Code Quick Reference: https://www.goinsight.ai/tools/error-codes/