Invokes (clicks) a UI element using the Windows Automation API. This endpoint provides a more reliable way to interact with UI elements compared to simulating mouse clicks, as it uses the native Windows accessibility framework.
This endpoint is the preferred method for interacting with UI elements in Windows applications when you have the element's ID.
Important: The element ID must be obtained from either the System Overview
or Get Automation Details endpoints. The ID corresponds
to the Id property of UI elements found in these responses.
Before using this endpoint, ensure that:
SupportsInvoke property)This endpoint requires a single parameter: the ID of the UI element to invoke.
| Property | Type | Description |
|---|---|---|
elementId Required |
String | The composite identifier of the UI element to invoke. This ID can be found in the System Overview or Automation Details responses. |
{
"elementId": "W-Notepad|B-File"
}The endpoint returns a simple response object indicating whether the operation was successful.
| Property | Type | Description |
|---|---|---|
success |
Boolean | Indicates whether the operation was successful. |
message |
String | A message describing the result of the operation. |
{
"success": true,
"message": "Click executed (using Windows Automation)"
}{
"success": false,
"message": "Element not found"
}
Note: If you attempt to use this endpoint with an HTML element in a Chrome browser, you'll receive an error message instructing you to use Chrome-specific actions like chromeClickElement instead.
SupportsInvoke property in the element details to check if an element supports this operation.import requests
import json
# API configuration
BASE_URL = "http://localhost:54321"
API_KEY = "your-api-key" # Replace with your actual API key
# Headers
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
}
# Invoke a UI element
def invoke_element(element_id):
url = f"{BASE_URL}/tools-api/automation/invoke"
payload = {
"elementId": element_id
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 200:
return response.json()
else:
print(f"Error: {response.status_code}")
print(response.text)
return None
# Example usage
element_id = "W-Notepad|B-File" # Example element ID
result = invoke_element(element_id)
print(json.dumps(result, indent=2))import axios from 'axios';
// API configuration
const BASE_URL = 'http://localhost:54321';
const API_KEY = 'your-api-key'; // Replace with your actual API key
// Headers
const headers = {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`
};
// Invoke a UI element
async function invokeElement(elementId: string): Promise {
try {
const url = `${BASE_URL}/tools-api/automation/invoke`;
const payload = {
elementId: elementId
};
const response = await axios.post(url, payload, { headers });
return response.data;
} catch (error) {
console.error('Error invoking element:', error);
throw error;
}
}
// Example usage
(async () => {
try {
const elementId = 'W-Notepad|B-File'; // Example element ID
const result = await invokeElement(elementId);
console.log(JSON.stringify(result, null, 2));
} catch (error) {
console.error('Operation failed:', error);
}
})(); using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
public class ToolsServerClient
{
private readonly HttpClient _httpClient;
private readonly string _baseUrl;
public ToolsServerClient(string apiKey, string baseUrl = "http://localhost:54321")
{
_baseUrl = baseUrl;
_httpClient = new HttpClient();
_httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
}
/// <summary>
/// Invokes a UI element using its ID.
/// </summary>
/// <param name="elementId">The composite identifier of the UI element.</param>
/// <returns>Response containing success status and message.</returns>
public async Task<ActionResponse> InvokeElementAsync(string elementId)
{
var requestData = new { ElementId = elementId };
var jsonContent = JsonSerializer.Serialize(requestData);
var content = new StringContent(jsonContent, Encoding.UTF8, "application/json");
var response = await _httpClient.PostAsync($"{_baseUrl}/tools-api/automation/invoke", content);
var responseBody = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
// Attempt to deserialize error response, or throw generic exception
try
{
var errorResponse = JsonSerializer.Deserialize<ActionResponse>(responseBody, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
// You might want to throw a custom exception here including the message
throw new HttpRequestException($"Error invoking element: {errorResponse?.Message ?? "Unknown error"} (Status code: {response.StatusCode})");
}
catch (JsonException)
{
throw new HttpRequestException($"Error invoking element: {response.ReasonPhrase} (Status code: {response.StatusCode}). Response body: {responseBody}");
}
}
return JsonSerializer.Deserialize<ActionResponse>(responseBody, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
}
}
// Define Request/Response classes if not already defined elsewhere
// Assuming ActionResponse class exists as shown in other examples:
public class ActionResponse
{
public bool Success { get; set; }
public string Message { get; set; }
public DateTime Timestamp { get; set; } // Assuming timestamp is returned, adjust if needed
}
// Example usage
class Program_InvokeElementExample // Renamed to avoid conflict if copy-pasted directly with other examples
{
static async Task Main_InvokeElement() // Renamed Main
{
var client = new ToolsServerClient("your_api_key_here");
string elementToInvoke = "W-Notepad|B-File"; // Example ID
try
{
var result = await client.InvokeElementAsync(elementToInvoke);
Console.WriteLine($"Success: {result.Success}");
Console.WriteLine($"Message: {result.Message}");
// Console.WriteLine($"Timestamp: {result.Timestamp}"); // Uncomment if timestamp is expected
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
}
}