Remote operation

Tool Name: airdroid_business_remote_operation

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Device Management

Quick Start (Copy & Use)

One-liner: Get embedded frame access credentials for a device — returns a redirect URL and access token for remote access

What you need: DeviceId (device ID)

Success criteria: StatusCode = 200 and ErrorMessage is an empty string; returns RedirectUrl and ExpiresIn

What to do next: Open the RedirectUrl directly in a browser to access the device remote control page, or embed it in an iframe for integration into custom web applications

Minimal request example:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Minimal response example:

{
  "RedirectUrl": "https://example.com/embed",
  "ExpiresIn": 120,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Quick remote access via browser

Scenario: An IT technician needs to quickly access a device's screen remotely for troubleshooting

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

After receiving the response, open the RedirectUrl directly in a browser. The URL is valid for ExpiresIn seconds.

Recipe 2: Embed device view in a custom dashboard

Scenario: Integrate device remote access into an internal IT management portal

{
  "DeviceId": "abc123def456"
}

Use the returned RedirectUrl as the src attribute of an HTML iframe:

Recipe 3: Look up device then get remote access

Scenario: Only the device name is known — first look up the device ID, then get remote access credentials

1. Call Get a Device by Name:

{
  "DeviceName": "Warehouse-Tablet-001"
}

1. Use the returned device_id to call Remote Operation:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

1. Overview

1.1 Description

Get embedded frame access credentials for a device. Returns a redirect URL and an access token for embedding a device management interface in an iframe or opening it directly in a browser. The access token automatically expires after the specified ExpiresIn seconds.

1.2 When to Use

• Remote troubleshooting: When an IT technician needs to remotely view or control a device's screen
• Custom portal integration: When embedding device management into a custom web application or internal dashboard
• Temporary access: When providing time-limited access to a device view without full account access
• Third-party integration: When integrating AirDroid Business device control into third-party dashboards or monitoring systems
• Remote camera access: When needing to view a device's camera feed remotely

1.3 Execution Mode & Response

This operation is synchronous — results are returned immediately after the call.

• Response: RedirectUrl, ExpiresIn, StatusCode, ErrorMessage
• No tracking needed: Synchronous operation, no Pid returned
• Token expiration: The generated access token expires after ExpiresIn seconds
• Usage: The RedirectUrl can be clicked directly in a browser or embedded as an iframe src

1.4 Prerequisites

Important: The account must have all three permissions (Remote Control, Observation Mode, and Remote Camera) for full functionality.

1.5 Prerequisite Tools

1.6 Comparison with Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceId`

Device unique identifier, specifying the target device for remote access.

• Type: string
• Format: Non-empty string
• Source:
  1. Obtained via the Get All Devices tool; use the device_id field from the response
  2. Obtained via the Get a Device by Name tool for exact name lookup
• How to fill in a GI node:
  • Constant: Enter the device ID string directly, e.g. fa6edcff65ab444e8b5e0eb08df4175d
  • Upstream reference: Map from the Get All Devices node's Devices[0].device_id field
• Example:

  "fa6edcff65ab444e8b5e0eb08df4175d"

2.3 Parameter Combination Logic

• Only one parameter is required
• The DeviceId must correspond to a valid, enrolled device

3. Outputs

3.1 Response Examples

Success response:

{
  "RedirectUrl": "https://example.com/embed",
  "ExpiresIn": 120,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Parameter error response:

{
  "RedirectUrl": "",
  "ExpiresIn": 0,
  "StatusCode": -1,
  "ErrorMessage": "Invalid device_id. Obtain via 'Get All Devices' or 'Get a Device by Name' tool."
}

Permission denied response:

{
  "RedirectUrl": "",
  "ExpiresIn": 0,
  "StatusCode": 200,
  "ErrorMessage": "API returned HTTP 403: {\"code\":0,\"msg\":\"Permission denied\"}"
}

Network error response:

{
  "RedirectUrl": "",
  "ExpiresIn": 0,
  "StatusCode": 500,
  "ErrorMessage": "Request timeout after 60 seconds."
}

3.2 Field Descriptions

3.3 Status Code / Enum Value Mapping

4. Examples

4.1 Basic Example: Get remote access URL

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Response:

{
  "RedirectUrl": "https://example.com/embed",
  "ExpiresIn": 120,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Usage: Open https://example.com/embed in a browser within 120 seconds to access the device remotely.

4.2 Advanced Example: Look up device then get remote access

Step 1: Call Get a Device by Name to get device information

{
  "DeviceName": "Warehouse-Tablet-001"
}

Response (simplified):

{
  "Device": {
    "device_id": "fa6edcff65ab444e8b5e0eb08df4175d",
    "device_name": "Warehouse-Tablet-001"
  }
}

Step 2: Call Remote Operation with the device ID

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Step 3: Open the returned RedirectUrl in a browser or embed in an iframe

4.3 Error Example: Invalid device ID

Request:

{
  "DeviceId": "invalid_device_id"
}

Response:

{
  "RedirectUrl": "",
  "ExpiresIn": 0,
  "StatusCode": -1,
  "ErrorMessage": "Invalid device_id. Obtain via 'Get All Devices' or 'Get a Device by Name' tool."
}

4.4 Error Example: Insufficient permissions

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Response:

{
  "RedirectUrl": "",
  "ExpiresIn": 0,
  "StatusCode": 200,
  "ErrorMessage": "API returned HTTP 403: {\"code\":0,\"msg\":\"Permission denied\"}"
}

Fix: Ensure the account has all three required permissions: Remote Control, Observation Mode, and Remote Camera.

5. Error Handling

5.1 AB Three-Layer Error Codes

Core principle: AB uses a three-layer error code strategy. The agent should decide how to handle based on StatusCode.

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Tips

• Token expiration awareness: The access token has a limited lifetime (ExpiresIn seconds). Generate a new URL if the previous one has expired.
• On-demand generation: Only generate the remote access URL when needed — do not pre-generate and cache, as the token will expire.

6.2 Security Considerations

⚠️ Access URL Security: The RedirectUrl contains an embedded access token. Do not share it with unauthorized users as it provides direct access to the device.

Pre-usage checklist:

1. ☐ Confirm the target device is correct
2. ☐ Confirm the account has all three required permissions
3. ☐ Use the URL promptly before it expires
4. ☐ Do not share the URL with unauthorized users

6.3 Idempotency

Idempotency: Each call generates a new access token and URL. Multiple calls are safe but each produces a unique token.

• Previous tokens remain valid until their expiration time
• There is no conflict between multiple active tokens for the same device

6.4 Iframe Integration Tips

When embedding the RedirectUrl in an iframe:

• Set appropriate width and height for optimal viewing experience (recommended: 1024x768 or larger)
• The iframe content provides interactive remote control of the device
• Consider using allow="fullscreen" attribute for better user experience
• Handle the token expiration in your application — refresh the URL when it expires

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Remote Troubleshooting Pattern

Scenario: An IT technician needs to remotely diagnose and fix a device issue

Tool chain:

Get a Device by Name → Remote Operation → (open URL in browser)

Steps:

1. Call Get a Device by Name to find the target device's device_id and confirm it is online
2. Call Remote Operation to get the RedirectUrl
3. Open the RedirectUrl in a browser to begin the remote troubleshooting session
4. Complete troubleshooting within the ExpiresIn validity period

8.2 Dashboard Integration Pattern

Scenario: Build a custom IT dashboard that provides one-click remote access to any managed device

Tool chain:

Get All Devices → (user selects device) → Remote Operation → (embed in iframe)

Steps:

1. Call Get All Devices to populate the device list in your dashboard
2. When a user selects a device, call Remote Operation with the selected device_id
3. Embed the returned RedirectUrl in an iframe within your dashboard
4. When the token expires, call Remote Operation again to get a fresh URL

8.3 Multi-Device Monitoring Pattern

Scenario: Monitor multiple devices by opening remote access sessions in separate browser tabs

Tool chain:

Get All Devices (filter target group) → [Loop] Remote Operation → (open each URL)

Steps:

1. Call Get All Devices with a group filter to get the devices to monitor
2. For each device, call Remote Operation to get a RedirectUrl
3. Open each URL in a separate browser tab for simultaneous monitoring
4. Refresh URLs as needed when tokens expire

Appendix Reference:

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