How to Build a Queue-it BotDeflector Tool for Browser Agents

For Hugging Face builders creating browser-agent demos, Spaces, or evaluation harnesses, BotDeflector should be exposed as a deterministic tool with an explicit schema. This full tutorial preserves both supported API contracts, the bounded polling client, coordinate handling, failure states, and authorization limits instead of reducing the integration to a short community announcement.

TL;DR

• Expose current Queue-it CAPTCHA handling to an agent as BotDeflector workflows, not as plain text recognition.
• Define a token tool around AntiBotdeflectorTaskProxyLess when inputs include the page URL, BotDeflector domain, and challenge flowToken; the asynchronous result is returned in solution.token.
• Define a visual tool around VisionEngine with module: "botdeflector" only for a visual challenge that provides foreground and background images; this request returns recognition coordinates directly.
• websiteURL and domain are separate BotDeflector fields and may contain different hostnames. Capture both from the authorized browser session.
• Bind tool execution to the Queue-it session that produced the observation because the returned result belongs to the challenge context that produced the inputs.
• Use this workflow only on Queue-it implementations you own, test, or have explicit permission to automate.

Queue-it virtual waiting rooms control access during traffic spikes such as ticket releases, product launches, and limited-inventory events. The CAPTCHA step used in current integrations is more than a picture containing characters: BotDeflector supplies a challenge flow that can require either a token result or visual coordinates.

This updated guide explains both supported paths with CapSolver. The token path is the default integration for a captured flowToken; the VisionEngine path applies when the browser exposes the corresponding foreground and background challenge images. CapSolver's CAPTCHA API documentation guide explains the shared task lifecycle and error model.

Define the tool contract before connecting an agent

For an agent tool schema, model Queue-it as BotDeflector rather than a standalone OCR form. A BotDeflector challenge contains session-bound inputs, and the expected output depends on the integration path:

Publish separate schemas because the modes are not interchangeable. Token mode does not accept a Base64 image as a substitute for flowToken, while visual recognition mode does not return the final BotDeflector token. Inspect the challenge implementation in your authorized browser session and choose the path matching the data available there.

Queue-it's traffic waiting room and the CAPTCHA solver also use different queues. The waiting room determines when a visitor may continue, while the CapSolver API processes a challenge task. The request queue glossary provides useful background for separating application queueing from API task polling.

Tool-design note: expose token mode and visual mode as separate typed tools so an agent cannot silently substitute images for flowToken or coordinates for a token.

Inputs for an agent-safe implementation

Provide these inputs to the tool backend:

• A CapSolver API key stored in an environment variable or secrets manager.
• A Queue-it page and BotDeflector challenge that you are authorized to test.
• The exact page URL where the challenge appears.
• For token mode: the BotDeflector domain and current flowToken captured from the same browser session.
• For visual mode: Base64-encoded foreground and background challenge images.
• An HTTP client that can send JSON requests to https://api.capsolver.com.

Do not place a production API key directly in source code. The examples use YOUR_API_KEY, FLOW_TOKEN_FROM_PAGE, and example domains as placeholders.

Tool path one: return a session-bound token

Token mode uses AntiBotdeflectorTaskProxyLess, then polls getTaskResult until CapSolver returns solution.token. The field names and response shape follow the current BotDeflector token-mode documentation.

Step 1: Capture the BotDeflector inputs

Let the browser layer capture these values from one authorized session:

• websiteURL: the full page URL where the BotDeflector challenge is running.
• domain: the BotDeflector domain required by that challenge.
• flowToken: the current challenge token exposed by the BotDeflector flow.

Do not encode an assumption that domain is simply the hostname from websiteURL. The official task definition treats them as separate inputs, and they may not use the same domain name.

Step 2: Create the token task

Forward the structured values to createTask:

curl --request POST 'https://api.capsolver.com/createTask' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "AntiBotdeflectorTaskProxyLess",
      "websiteURL": "https://queue.example.com/waitingroom/",
      "domain": "challenge.example.net",
      "flowToken": "FLOW_TOKEN_FROM_PAGE"
    }
  }'

The tool backend receives a task ID:

{
  "errorId": 0,
  "errorCode": "",
  "errorDescription": "",
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

Check errorId before storing taskId. If task creation fails, log errorCode and errorDescription without recording the API key or full challenge token.

Step 3: Poll for the BotDeflector token

Send the returned task ID to getTaskResult:

curl --request POST 'https://api.capsolver.com/getTaskResult' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
  }'

Keep the tool pending only while the response status is processing. Stop immediately if the API returns a nonzero errorId or a failed status. When the task is ready, read the token from solution.token:

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006",
  "status": "ready",
  "solution": {
    "token": "BOTDEFLECTOR_TOKEN"
  }
}

Step 4: Return the token to the same browser flow

Return the token to the browser executor for the BotDeflector integration point used by the same Queue-it browser session. Do not create a fresh browser context between capturing flowToken and applying the result. Session changes, navigation, or challenge refreshes can invalidate the context and require a new task.

The exact injection or submission point belongs to the Queue-it implementation you are testing. Capture it from your own application integration instead of relying on a universal selector.

Redeem Your CapSolver Bonus Code

Boost your automation budget instantly! Use bonus code CAP26 when topping up your CapSolver account to get an extra 5% bonus on every recharge — with no limits. Redeem it now in your CapSolver Dashboard

Reusable Python function for a tool backend

The backend example below creates a BotDeflector task, polls with a bounded timeout, and returns solution.token. It uses placeholder challenge values because a real flowToken must come from your authorized browser session.

import os
import time

import requests


API_BASE = "https://api.capsolver.com"
API_KEY = os.environ["CAPSOLVER_API_KEY"]


def solve_botdeflector(website_url, domain, flow_token, timeout=120):
    create_response = requests.post(
        f"{API_BASE}/createTask",
        json={
            "clientKey": API_KEY,
            "task": {
                "type": "AntiBotdeflectorTaskProxyLess",
                "websiteURL": website_url,
                "domain": domain,
                "flowToken": flow_token,
            },
        },
        timeout=30,
    )
    create_response.raise_for_status()
    created = create_response.json()

    if created.get("errorId"):
        raise RuntimeError(
            f"createTask failed: {created.get('errorCode')} - "
            f"{created.get('errorDescription')}"
        )

    task_id = created["taskId"]
    deadline = time.monotonic() + timeout

    while time.monotonic() < deadline:
        time.sleep(2)
        result_response = requests.post(
            f"{API_BASE}/getTaskResult",
            json={"clientKey": API_KEY, "taskId": task_id},
            timeout=30,
        )
        result_response.raise_for_status()
        result = result_response.json()

        if result.get("errorId"):
            raise RuntimeError(
                f"getTaskResult failed: {result.get('errorCode')} - "
                f"{result.get('errorDescription')}"
            )

        if result.get("status") == "ready":
            return result["solution"]["token"]

        if result.get("status") == "failed":
            raise RuntimeError("BotDeflector task failed")

    raise TimeoutError(f"BotDeflector task {task_id} exceeded {timeout}s")


token = solve_botdeflector(
    website_url="https://queue.example.com/waitingroom/",
    domain="challenge.example.net",
    flow_token="FLOW_TOKEN_FROM_PAGE",
)
print(token)

For more detail on environment variables, request handling, and reusable client structure, see the Python CAPTCHA API integration guide.

Tool path two: return visual coordinates

Expose the VisionEngine tool only when the challenge exposes the visual assets required by the BotDeflector recognition module. This path accepts a foreground image and an imageBackground, then returns click coordinates in the initial createTask response.

The request uses type: "VisionEngine" and module: "botdeflector":

curl --request POST 'https://api.capsolver.com/createTask' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "VisionEngine",
      "module": "botdeflector",
      "image": "BASE64_FOREGROUND_IMAGE",
      "imageBackground": "BASE64_BACKGROUND_IMAGE",
      "websiteURL": "https://queue.example.com/waitingroom/"
    }
  }'

According to the current VisionEngine documentation, this task returns recognition data directly; it does not require a separate getTaskResult request. A successful response has this shape:

{
  "errorId": 0,
  "errorCode": "",
  "errorDescription": "",
  "status": "ready",
  "solution": {
    "points": [[123, 88], [244, 84], [174, 70]]
  },
  "taskId": "TASK_ID"
}

Return points to an executor using the visual challenge in the same coordinate space as the submitted images. Scaling, cropping, or using a screenshot with different dimensions can move the target positions and cause incorrect interactions.

VisionEngine handles the recognition step; it does not replace the surrounding browser state management. If the page expects a subsequent token exchange, continue that exchange inside the same authorized session.

Evaluation cases for browser-agent builders

The task is created but never becomes ready

Evaluate whether the flowToken is current and belongs to the same page session. Also verify that websiteURL and domain were captured independently rather than constructed from one hostname. Use bounded polling and stop on API errors instead of looping indefinitely.

The returned token is rejected

A rejected token is a useful evaluation signal that that the page state changed after the challenge inputs were captured. Keep cookies, browser context, URL, and challenge state stable until the result is applied. If the challenge refreshes, capture a new flowToken and create a new task.

VisionEngine returns points but the clicks miss

Send the original challenge images without resizing them, and apply the coordinates against the same dimensions. Check whether your browser automation introduced device-pixel-ratio scaling, CSS resizing, or a cropped screenshot.

The integration works in a script but fails in CI

Compare browser versions, viewport settings, timing, cookies, and secret availability between local and CI environments. For a wider testing checklist, see CAPTCHA handling in automated QA.

Safety boundary for an agent tool

Deploy this agent capability only for systems you own, QA environments you operate, or workflows for which the site owner has granted explicit permission. A CAPTCHA-solving API does not grant access rights or override a site's terms, queue rules, rate limits, or authorization requirements.

Keep test volume bounded, avoid high-demand public events unless they are part of an approved test, and log only the minimum diagnostic data. API keys, cookies, flowToken values, and returned tokens should be treated as secrets and excluded from screenshots, analytics, and long-term logs.

Builder takeaway

Queue-it CAPTCHA handling now requires a BotDeflector-aware integration. Use AntiBotdeflectorTaskProxyLess for the session token flow and read the result from solution.token; use VisionEngine with the botdeflector module only when the challenge supplies the foreground and background images needed for coordinate recognition.

The agent-tool invariant is to preserve the original browser context from challenge capture through result submission. For authorized Queue-it testing, CapSolver provides both documented BotDeflector paths through the same task API.

FAQ

Q: What task type should I use for Queue-it BotDeflector token mode?

Define a token tool around AntiBotdeflectorTaskProxyLess when inputs include websiteURL, domain, and a current flowToken. Poll getTaskResult and read the completed value from solution.token.

Q: Does Queue-it BotDeflector token mode require a CAPTCHA image?

No. The token-mode task uses the page URL, BotDeflector domain, and flowToken. If the challenge instead exposes a foreground image and background image for visual recognition, use the separate VisionEngine path.

Q: When should I use the VisionEngine botdeflector module?

Define a visual tool around VisionEngine with module: "botdeflector" for the visual recognition step that supplies image and imageBackground. The API returns solution.points directly in the createTask response.

Q: Why can the BotDeflector domain differ from the Queue-it page URL?

BotDeflector defines websiteURL and domain as separate task fields, so the challenge service may use a hostname different from the visible Queue-it page. Capture both values from the active integration.

Q: Can I reuse a returned BotDeflector token in another browser session?

No reuse should be assumed. Apply the token to the same authorized browser flow that produced the challenge inputs; if the page or challenge refreshes, capture new inputs and create a new task.

Q: Is automated Queue-it CAPTCHA handling permitted?

It is appropriate only when you own the system or have explicit authorization to test or automate it. Respect the site's terms, access controls, queue policies, rate limits, and applicable law.