Sending and receiving API messages, request types

Sending API requests to the plugin and messages receiving. Supported message types and transmitted parameters. Methods for sending API messages.

Sometimes our customers have needs that can't be anticipated and preprogrammed by developers. In such cases we developed and still developing an API by which you can 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. Such function usually used for cross domain messaging between Window objects. A message sent to all listeners unilaterally without delivery confirmation, without callback or something like that.

For example lets take a look at an API request snippet to the AntiCaptcha plugin that will start a 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 messaage body, we'll back to it later. Line 7 defines a receiver domain, here will be always a current URL.

Message body is an object, which contains required and optional fields. A field receiver is always a string with antiCaptchaPlugin value, it shows our extension that message was addressed to it personally and not to someone else.

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

Receiving messages from the plugin

You can listen reply messages from the plugin. Usually it's an answer to the API request. Such messages contain a data field which has an sender field that equals to antiCaptchaPlugin and also a type of the last API request for which came the answer.

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 desscription of an operation or an error occured.

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: ""
    // }
});

Lets analyze this block. Lines 2-4 — a sender check to filter extraneous messages.

Lines from 8 to 15 contain a sample of a normal answer that can be received in response to the previous API request in order 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 sen an HTML element which contains a recaptcha that you need to solve.

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

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

In API request params pass a selector containerSelector (string) of HTML element that contains a recaptcha. Usually it's an element with g-recaptcha class name.

Message body example:

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

solveFuncaptcha

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

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

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

Message body:

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

solveHcaptcha

Same as a solveRecaptcha method but gives you an ability set an HTML element with hCaptcha that will be solved. When you need to solve only a particular hCaptcha on a web-page.

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

In the containerSelector (string) field you need to pass a hCaptcha container, usually it equals to .h-captcha, you can pass any higher-level ancestor — the plugin will find a hCaptcha inside of 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 mark manually an image and an input as a captcha source and a solution destination accordingly for a certain domain.

Passed parameters:

imageSelector (string) — a selector for 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 of these two selectors or both should be transferred.

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

saveInStorage (boolean) — save of 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 it's needed to escape special characters if they are used in the HTML element id or class name e.g. ":", ">", "#" etc. You should use double characters escaping.

For example for 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 the need 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 where captchas should or should not be solved depending on the mode (see below).
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 solution on the same web-page
startRecaptcha2SolvingWhenChallengeShown (boolean, default false) — Turn On/Off solving when a challenge box is 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

There are several places from which you can send API requests to the plugin, we will show you few of them.

From a browser console

The most obvious, simple but not convenient transmission method. But you can open on any web-page a browser console (usually F12 key) and put there a window.postMessage method call with parameters and press Enter. The plugin will get the message then process it and will necessary action and also it will send a reply which can be listened the same way from this console.

From any web-page

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

From other browser extension

You can transfer API messages calling JS code from other extension. You only need to call it as a Content script, i.e. code that runs in 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).

There is other ways to send API message but we'll describe it later.

Using iMacros

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