Integration Guide

Quick Start

BotFlush can be integrated in 3 steps: load the widget, render it, and verify tokens server-side.

1. Load the Widget

Add the widget script to your page. It loads asynchronously and won't block rendering.

<script src="https://challenge.botflush.com/widget.js" async defer></script>

2. Add the Container

Place a container element where you want the CAPTCHA checkbox to appear.

<div id="bf-captcha" data-sitekey="YOUR_SITE_KEY"></div>

3. Verify Server-Side

When the user completes the challenge, a token is generated. Send it to your server and verify via API.

POST https://challenge.botflush.com/api/siteverify
Content-Type: application/json

{
  "secret": "YOUR_SECRET_KEY",
  "token": "TOKEN_FROM_CLIENT"
}

Response:
{
  "success": true,
  "site_key": "YOUR_SITE_KEY",
  "timestamp": "2026-04-15T12:00:00Z"
}

JavaScript API

BotFlush.render()

Programmatically render the widget into a container element.

BotFlush.render('bf-captcha', {
  siteKey: 'YOUR_SITE_KEY',
  callback: function(token) {
    // Token received — send to your server
    console.log('Verified:', token);
  },
  'expired-callback': function() {
    // Token expired — prompt user to re-verify
  },
  'error-callback': function() {
    // Error occurred
  }
});

BotFlush.reset()

Reset the widget to its initial state. Useful after form submission.

BotFlush.reset();

BotFlush.getResponse()

Get the current verification token string. Returns empty string if not yet verified.

var token = BotFlush.getResponse();

reCAPTCHA Compatibility

BotFlush implements the reCAPTCHA v2 API specification. If you're migrating from Google reCAPTCHA, you only need to change two things:

Migration Example

Change your existing reCAPTCHA integration:

<!-- Before (reCAPTCHA) -->
<script src="https://www.google.com/recaptcha/api.js"></script>
<div class="g-recaptcha" data-sitekey="GOOGLE_KEY"></div>

<!-- After (BotFlush) -->
<script src="https://challenge.botflush.com/widget.js"></script>
<div class="g-recaptcha" data-sitekey="BOTFLUSH_KEY"></div>

Server-side: update the verification endpoint from google.com/recaptcha/api/siteverify to challenge.botflush.com/api/siteverify. Request and response formats are identical.

GDPR Compliance

BotFlush is designed with privacy by default. No personal data is collected, no browser fingerprinting is performed, and no data is shared with third parties.

Enabling Strict GDPR Mode

For sites serving EU users that require explicit consent flows:

1. Log in to the BotFlush Console
2. Navigate to the site settings for your domain
3. Enable GDPR Strict Mode
4. This disables all optional analytics and ensures zero-cookie operation

GDPR strict mode is available on all plans. Enterprise plans include additional controls for data residency and geofencing.

Verification Modes

BotFlush offers multiple challenge engines. You can configure which engines to use per-site in the Console.

Server-Side Verification

The verify endpoint accepts a standard POST request. Here are examples in common languages.

Node.js

const res = await fetch('https://challenge.botflush.com/api/siteverify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    secret: process.env.BOTFLUSH_SECRET,
    token: req.body['bf-token']
  })
});
const data = await res.json();
if (!data.success) return res.status(403).send('Verification failed');

Python

import requests

resp = requests.post('https://challenge.botflush.com/api/siteverify', json={
    'secret': BOTFLUSH_SECRET,
    'token': request.form['bf-token']
})
if not resp.json().get('success'):
    abort(403)

PHP

$response = file_get_contents('https://challenge.botflush.com/api/siteverify', false,
  stream_context_create(['http' => [
    'method' => 'POST',
    'header' => 'Content-Type: application/json',
    'content' => json_encode([
      'secret' => BOTFLUSH_SECRET,
      'token' => $_POST['bf-token']
    ])
  ]])
);
$result = json_decode($response, true);
if (!$result['success']) { http_response_code(403); exit; }

Go

payload, _ := json.Marshal(map[string]string{
    "secret": os.Getenv("BOTFLUSH_SECRET"),
    "token":  r.FormValue("bf-token"),
})
resp, _ := http.Post("https://challenge.botflush.com/api/siteverify",
    "application/json", bytes.NewBuffer(payload))
var result struct{ Success bool }
json.NewDecoder(resp.Body).Decode(&result)
if !result.Success { w.WriteHeader(403); return }

Downloads

Node Inspector — Chrome Extension

See which BotFlush edge node served your verification challenge on any website using BotFlush. A small badge appears at the bottom-right corner showing the node URL.