CaptchaSonic Module for Browser Automation Studio

Automated CAPTCHA solving for Browser Automation Studio (BAS), powered by the CaptchaSonic API.

Detect a supported CAPTCHA, extract the required challenge data, send it to CaptchaSonic, and return the result directly to your BAS workflow.

📋 Table of Contents

Overview
Features
Supported CAPTCHA Types
Installation
Quick Start
Available Actions
Configuration
Result Format
Usage Example
Troubleshooting
Compatibility
Project Structure
License
Support

🚀 Overview

CaptchaSonic is a Browser Automation Studio (BAS) module that connects your BAS workflows to the CaptchaSonic API.

The module handles the complete solve workflow:

Detect the CAPTCHA on the current page or frame.
Extract the required challenge information.
Submit the challenge to the CaptchaSonic API.
Wait for the solution.
Apply the returned result to the page.
Return a structured JSON result to BAS.

The module is designed to work directly inside BAS without a separate build system or package manager.

⚠️ API key required

CaptchaSonic does not ship with a shared production API key. Configure the module with your own API key obtained from your CaptchaSonic account.

✨ Features

Automatic workflow — Detection, extraction, solving, and result application are handled by the module.
Multiple CAPTCHA families — Supports 12 CAPTCHA types through dedicated BAS actions.
Frame-aware operation — Supports CAPTCHA challenges hosted inside nested frames where applicable.
Configurable timeouts — Configure API timeouts from 5 to 900 seconds.
Configurable retries — Configure between 1 and 20 attempts.
Per-thread device identity — Maintain a persistent device identifier for request signing.
Accuracy reporting — Optionally report solve accuracy using reportAccuracy.
Custom API endpoint — Configure an alternative endpoint when required.
Bilingual interface — Action dialogs support English and Russian.
ES5 compatible — Designed for BAS's JavaScript environment.
Zero external dependencies — No npm installation or build step required.
No bundled API credentials — API credentials are supplied by the user.

🛡️ Supported CAPTCHA Types

CAPTCHA	BAS Action
PopularCaptcha	`CaptchaSonicSolvePopularCaptcha`
reCAPTCHA v2	`CaptchaSonicSolveReCaptcha2`
Geetest v3 / v4	`CaptchaSonicSolveGeetest`
BLS OCR	`CaptchaSonicSolveBls`
mtCaptcha OCR	`CaptchaSonicSolveMtCaptcha`
Generic Slide	`CaptchaSonicSolveSlide`
CaptchaFox	`CaptchaSonicSolveCaptchaFox`
Binance	`CaptchaSonicSolveBinance`
Tencent	`CaptchaSonicSolveTencent`
AWS WAF	`CaptchaSonicSolveAwsWaf`
TikTok	`CaptchaSonicSolveTikTok`
Prosopo / Procaptcha	`CaptchaSonicSolveProsopo`

Management Actions

Action	Purpose
`CaptchaSonicConfigure`	Configure API credentials and client settings
`CaptchaSonicCheckBalance`	Validate the API key and retrieve account balance
`CaptchaSonicReportAccuracy`	Report whether a previous solution was correct

📦 Installation

1. Download

Download the latest CaptchaSonic-<version>.zip from the project's GitHub Releases page.

2. Import into BAS

Open:

BAS → Settings → Modules → Import module

Select the module directory containing:

manifest.json

3. Verify installation

After importing the module, you should see a CaptchaSonic category in the BAS action list.

No npm installation, compilation, or additional dependency installation is required.

⚡ Quick Start

Step 1 — Get an API key

Create or retrieve your personal API key from:

https://captchasonic.com

Step 2 — Configure the module

Add:

CaptchaSonic → Configure

Provide your API key and, if necessary, configure the endpoint and client version.

Step 3 — Add a solver action

Add the solver corresponding to the CAPTCHA type you need to process.

For example:

CaptchaSonic → Solve → reCAPTCHA v2

Step 4 — Read the result

The solver writes a JSON result to the configured BAS variable.

Example:

{
  "solved": true,
  "type": "ReCaptcha2",
  "attempts": 1,
  "code": "03AGdBq...",
  "action": "CaptchaSonicSolveReCaptcha2",
  "message": "OK"
}

Your workflow can then branch based on the solved property.

⚙️ Available Actions

`CaptchaSonicConfigure`

Configures the settings used by subsequent CaptchaSonic actions.

Parameter	Description
API key	Your personal CaptchaSonic API key.
Custom endpoint	Optional API endpoint override.
Client version	Value sent through the `X-Extension-Version` header.

The API key should be treated as a secret and should not be committed to source control.

`CaptchaSonicCheckBalance`

Checks whether the supplied API key is valid and retrieves the current account balance.

Parameter	Description
API key	CaptchaSonic API key.
Result variable	BAS variable receiving the response.

`CaptchaSonicSolve*`

Each supported CAPTCHA type has its own dedicated solve action.

Common parameters include:

Parameter	Description	Default
API key	CaptchaSonic API key	Required
Custom endpoint	Optional API endpoint override	Default endpoint
Client version	`X-Extension-Version` value	Configured value
Timeout	Maximum API wait time in seconds	`120`
Retry count	Number of solve attempts	`3`
Open widget automatically	Attempts to open the CAPTCHA widget before solving	Enabled
Force English prompt	Requests an English prompt where supported	Disabled
Report accuracy automatically	Sends accuracy feedback after a solve	Disabled
Result variable	Variable containing the JSON result	Required
Device ID variable	Persistent per-profile device identifier	Optional
Frame selector	Manually target a nested frame	Optional
Extra site configs	Additional JSON configuration for supported solvers	Optional

Timeout

Valid range:

5–900 seconds

Retry count

Valid range:

1–20 attempts

`CaptchaSonicReportAccuracy`

Reports whether a previously returned solution was correct.

This can be used manually when automatic accuracy reporting is disabled.

📊 Result Format

Solver actions return a JSON object similar to:

{
  "solved": true,
  "type": "ReCaptcha2",
  "attempts": 1,
  "code": "03AGdBq...",
  "action": "CaptchaSonicSolveReCaptcha2",
  "message": "OK"
}

Result fields

Field	Description
`solved`	Whether the solve operation succeeded
`type`	CAPTCHA type processed
`attempts`	Number of attempts used
`code`	Returned solution value, when applicable
`action`	BAS action that produced the result
`message`	Human-readable status message

The exact fields available may vary depending on the CAPTCHA type and API response.

🖥️ Usage Example

A typical BAS workflow can look like:

[Start]
   ↓
[CaptchaSonic: Configure]
   ↓
[Navigate to website]
   ↓
[CaptchaSonic: Solve reCAPTCHA v2]
   ↓
[Read result variable]
   ↓
[Check solved]
   ├── true  → Continue workflow
   └── false → Handle failure / retry

Example result handling

If the configured result variable is:

VAR_CS_RESULT

the workflow can parse the JSON response and check:

solved == true

before continuing.

🔧 Configuration

CaptchaSonic supports both global configuration and per-action overrides.

Default endpoint

https://api.captchasonic.com

Custom endpoint

A custom endpoint can be configured when your deployment requires an alternative API URL.

Client version

The module sends the configured client version using:

X-Extension-Version

If the API returns HTTP 426, the client version may need to be updated.

Device identity

Solver actions can use a persistent device ID stored in a BAS variable.

Example:

CS_DEVICE_ID

This allows the same BAS profile/thread to retain its configured device identity between actions.

🧩 Troubleshooting

`An API key is required.`

No API key was supplied.

Fix: Configure the module with your personal CaptchaSonic API key.

Shared/demo API key error

If the module reports that a bundled/shared key cannot be used, replace it with your own account API key.

`NOT READY` or missing JavaScript globals

Older BAS environments may not provide some JavaScript compatibility functions.

Make sure:

engine_compat.js

is loaded before the other engine files. It is listed first in the module manifest.

HTTP `426`

The API rejected the supplied client version.

Fix: Update the X-Extension-Version value through CaptchaSonicConfigure or the relevant action configuration.

Solution is not applied

The CAPTCHA may be inside a nested frame that could not be detected automatically.

Fix: Use the advanced Frame selector option to explicitly target the required frame.

Timeout error

If the timeout is rejected, verify that the configured value is between:

5 and 900 seconds

CAPTCHA-specific issues

If a particular CAPTCHA type fails consistently:

Confirm that the correct solver action is being used.
Verify the API key and endpoint.
Check the returned JSON result.
Increase the timeout if the challenge requires additional processing time.
Enable additional frame configuration when the challenge is hosted in a nested frame.

🗂️ Project Structure

The module is intentionally distributed without a build pipeline.

A typical installation contains:

CaptchaSonic/
├── manifest.json
├── interface_*.js
├── select_*.js
├── code_*.js
├── engine_*.js
└── README.md

Each BAS action is represented by its corresponding interface, selection, and code files.

The shared engine files provide common functionality across the actions.

🔐 Security & Credentials

Your CaptchaSonic API key is a credential.

Do not:

Commit API keys to Git.
Include keys in public screenshots.
Share keys in issue reports.
Hard-code production credentials into reusable workflows.

Instead, configure credentials through your BAS environment or another secure secret-management mechanism appropriate for your deployment.

If a key is accidentally exposed, revoke or rotate it through your CaptchaSonic account.

🌐 Compatibility

CaptchaSonic is designed for:

Browser Automation Studio
ES5-compatible JavaScript
BAS module installations using manifest.json

The module does not require:

Node.js
npm
Webpack
Babel
A separate build process

📄 License

Released under the MIT License.

See LICENSE for the complete license text.

💬 Support

Website: https://captchasonic.com
Email: support@captchasonic.com
Repository: https://github.com/Captcha-Sonic/CaptchaSonic

When reporting an issue, include:

BAS version
CaptchaSonic module version
CAPTCHA type
Relevant action name
Error message
Sanitized result JSON

Never include your API key in an issue or support request.

CaptchaSonic

CAPTCHA solving for Browser Automation Studio

Made for BAS workflows · ES5 compatible · Zero dependencies

Name		Name	Last commit message	Last commit date
LICENSE		LICENSE
README.md		README.md
SonicBAS.png		SonicBAS.png
sonicBanner.png		sonicBanner.png

Uh oh!

Latest commit

History

Folders and files

Repository files navigation