Sending and receiving API messages, request types

Sometimes our customers have needs that developers can't anticipate or preprogram. For such cases, we've developed and are still developing an API that allows you to, for example, solve only one particular recaptcha, set image and input selectors, etc.

Senging messages to the plugin

You can send a request to our plugin using a window.postMessage method. This function is usually used for cross-domain messaging between Window objects. A message sent to all listeners unilaterally without delivery confirmation, without callback or anything like that.

For example, let's take a look at an API request snippet to the AntiCaptcha plugin that starts the recaptcha solving process. We'll describe every line of this code.

window.postMessage( { receiver: 'antiCaptchaPlugin', type: 'solveRecaptcha', containerSelector: '.g-recaptcha' }, window.location.href );

Lines from 2 to 6 contain the message body, we'll come back to that later. Line 7 defines a receiver domain. There is always a current URL here.

The message body is an object containing required and optional fields. A field receiver is always a string with anantiCaptchaPlugin value, showing our extension that the message was addressed to it personally and not to someone else.

The field type determines the message type. In other words, an action to be taken. In our example, we ask the plugin to solve a recaptcha whose container is presented on the web page by an HTML object with class g-recaptcha. A selector that defines such elements is set in the last containerSelector field.

Receiving messages from the plugin

You can listen to reply messages from the plugin. These are usually answers to API requests and contain a data field with a sender field that equals theantiCaptchaPlugin and also the last type of API request that was answered.

status — status of the last request. Possible values ok — a request was successful, error — an error occured.
errorId — id of an error, equals 0 if no error happened.
errorText — text description of the error, always corresponds to the errorId.
messageText — usually a detailed description of an operation or an error occured.

The next piece of code shows how you can subscribe to a message receiving.

window.addEventListener('message', function (event) { if (typeof event.data.sender === 'undefined' || event.data.sender != 'antiCaptchaPlugin') { return; } // event.data contains all the data that were passed console.log(event.data); // { // sender: "antiCaptchaPlugin" // type: "solveRecaptcha" // status: "ok" // errorId: 0 // errorText: "" // messageText: "" // } });

Let's analyze this block. Lines 2to4 — a sender check to filter extraneous messages.

Lines 8 to 15 contain a sample of a normal answer in response to the previous API request to solve a recaptcha (type == solveRecaptcha). It means that a selector passed a test, and if a recaptcha is found in this container, it will begin to be solved.

Supported message types

solveRecaptcha

Allows you to send an HTML element containing a recaptcha that you need to solve.

This message type is good when you need to solve a particular recaptcha or any recaptchas found on a web page.

You need to turn off Solve reCAPTCHA 2 (I'm not a robot) automatically mode (in the plugin options).

In API request parameters please provide a selector containerSelector (string) of HTML element that contains a recaptcha. It's usually an element with ag-recaptcha class name.

Message body example:

{ receiver: 'antiCaptchaPlugin', type: 'solveRecaptcha', containerSelector: '.g-recaptcha' }

solveFuncaptcha

Same as the solveRecaptcha method but allows you to set an HTML element with Funcaptcha that will be solved. When you only need to solve a particular Funcaptcha on a web page.

It makes sense to disable the Solve Funcaptcha automatically setting in the plugin options.

In the containerSelector (string) field you need to pass a funcaptcha container. It usually equals #funcaptcha, but you can pass any higher-level ancestor — the plugin will find a funcaptcha inside it.

Message body:

{ receiver: 'antiCaptchaPlugin', type: 'solveFuncaptcha', containerSelector: '#funcaptcha' }

solveHcaptcha

Same as the solveRecaptcha method but enables you to set an HTML element with hCaptcha that will be solved when you only need to solve a particular hCaptcha on a web page.

It makes sense to disable the Solve hCaptcha automatically setting in the plugin options.

In the containerSelector (string) field you need to pass an hCaptcha container, which is usually equal to .h-captcha. You can pass any higher-level ancestor — the plugin will find an hCaptcha inside it.

Message body:

{ receiver: 'antiCaptchaPlugin', type: 'solveHcaptcha', containerSelector: '.h-captcha' }

setImageCaptchaSelectors

Sets an image captcha and input field selectors for a target domain.

Eliminates the need to manually mark an image and an input as a captcha source and solution destination respectively for a certain domain.

Passed parameters:

imageSelector (string) — a selector for an image that will be treated as a captcha. Pass a null value to cancel.

inputSelector (string) — similary, a selector for finding an input field which will get a captcha result. Pass a null value to cancel.

One or both of these two selectors should be transferred.

domain (string) — a domain where the above selectors will be applied. Optional, if not passed, a current domain where the API call occurred will be used.

saveInStorage (boolean) — save or don't save transferred selectors in the browser storage for further usage. Optional, default true. May be used when you need to solve an image captcha once on a current web page and do not solve it after page refreshing.

Message body example:

{ receiver: 'antiCaptchaPlugin', type: 'setImageCaptchaSelectors', // for web page https://antcpt.com/rus/information/demo-form/image.html imageSelector: '#htest_image', inputSelector: '#vericode', domain: 'antcpt.com', saveInStorage: true }

Sometimes you need to escape special characters if they are used in the HTML element id or class name, e.g., ":", ">", "#" etc. You should use double characters to escape.

For example, for an element with id == "loginPage:SiteTemplate" you pass the following selector.
Pay attention that we do not escape the first # symbol because it's not part of the element identificator, but a directive to a browser to search the element through identificator. "#loginPage\\:SiteTemplate" To select a proper selector it's convenient to open a browser console (F12 key, Console tab) and use document.querySelector method.
E.g. document.querySelector('#loginPage\\:SiteTemplate')

setOptions

You can set plugin options without having to do it manually.

Passed parameters:

options (object) — an object with parameters that you wanna set. Which can be:

• enable (boolean, default true) — turn ON (true) / OFF (false) the extension
• antiCaptchaApiKey (string, default <empty>) — your anti-captcha.com API account key


• autoSubmitForm (boolean, default false) — Auto submit FORM after solving
• playSounds (boolean, default false) — Turn on/off sound mode


• whereSolveList (array, default []) — Domain list usage mode. If false then list will be considered as black, if true — white. In the black list mode, captchas on listed domains will NOT be solved. In white mode — on domains from the list only.
• whereSolveListIsWhite (boolean, default false) — Domain list usage mode. If false then list will be considered as black, if true — white. In the black list mode captchas on listed domains will NOT be solved. In white mode — on domains from the list only.


• solveRecaptcha2 (boolean, default true) — Turn On/Off reCAPTCHA 2 automatic solving
• solveInvisibleRecaptcha (boolean, default true) — Turn On/Off invisibile reCAPTCHA automatic solving
• solveRecaptcha3 (boolean, default true) — Turn On/Off reCAPTCHA 3 automatic solving
• recaptcha3Score (integer, default 0.3) — Desired reCAPTCHA 3 score
• solveFuncaptcha (boolean, default true) — Turn On/Off Funcaptcha automatic solving
• solveGeetest (boolean, default true) — Turn On/Off Geetest automatic solving
• solveHcaptcha (boolean, default true) — Turn On/Off hCaptcha automatic solving
• usePredefinedImageCaptchaMarks (boolean, default true) — Turn On/Off automatic image CAPTCHA selection and solution


• useRecaptchaPrecaching (boolean, default false) — Enable / disable reCAPTCHA 2 precaching feature
• kPrecachedSolutionCountMin (integer, default 2) — K-number (precachedSolutionsCountK) min
• kPrecachedSolutionCountMax (integer, default 4) — K-number (precachedSolutionsCountK) max


• dontReuseRecaptchaSolution (boolean, default true) — Do not reuse previous reCAPTCHA 2 solutions on the same web page
• startRecaptcha2SolvingWhenChallengeShown (boolean, default false) — Turn On/Off solving when a challenge box is in shown mode
• solveOnlyPresentedRecaptcha2 (boolean, default false) — Do not solve hidden on a web page reCAPTCHA 2


• solveProxyOnTasks (boolean, default false) — Turn On/Off ProxyOn tasks Solving
• userProxyProtocol (enum, default http, required if solveProxyOnTasks is ON) — Proxy type (http, https, socks4, socks5)
• userProxyServer (string, required if solveProxyOnTasks is ON) — Proxy server address, only *.*.*.* mask allowed
• userProxyPort (integer, required if solveProxyOnTasks is ON) — Proxy port
• userProxyLogin (string, default empty) — Proxy login
• userProxyPassword (string, default empty) — Proxy password


• setIncomingWorkersUserAgent (boolean, default true) — Turn On/Off incoming worker's User-Agent setting for some captchas (e.g. Hcaptcha)
• runExplicitInvisibleHcaptchaCallbackWhenChallengeShown (boolean, default false) — Turn On/Off callback running when a challenge box is shown mode for explicit invisible Hcaptcha
• delayOnreadyCallback (boolean, default false) — Turn on/off delay for onReady callback
• reenableContextmenu (boolean, default false) — Force browser to show context menu (Deprecated, removed)

Example:

{ receiver: 'antiCaptchaPlugin', type: 'setOptions', options: { antiCaptchaApiKey: '12345678900987654321' } }

Methods for sending API messages

You can send API requests to the plugin from several places. Here are a few of them.

From a browser console

The most obvious, simple but inconvenient transmission method. You can, however, open any web page on a browser console (usually F12 key), put there a window.postMessage method call with parameters, and press Enter. The plugin will get the message, process it, take the necessary action, and send a reply, which can be listened to in the same way from this console.

From any web page

You can create a web page on any domain and include a JavaScript code to run all the requests. For example, you can mark any images as captcha sources and input fields as solution destinations. Do not forget to pass a domain that will use the current selectors.

From other browser extensions

You can transfer API messages calling JS code from other extensions. You only need to call it as a Content script, i.e., code that runs in a web page context. For example, it can be a script launcher from your homemade extension or from User Script extensions like Tampermonkey (Chrome) or Greasemonkey (Firefox).

Using iMacros

You can use a tool that may help you to convert JS code with API requests into iMacros single-line script.