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.

Attention, API is available starting from 0.1800 version. We are still developing this functional so keep your plugin version updated to have all the methods and features.

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 prticular recaptcha and not every 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) and 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 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' }

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 }

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

  • 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

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

  • solveFuncaptcha (boolean, default false) — Turn On/Off Funcaptcha automatic solving
  • usePredefinedImageCaptchaMarks (boolean, default true) — Turn On/Off automatic image CAPTCHA selection and solution
  • 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.