Botpoison Integration - SpamBlock Pixel

Learn how to integrate SpamBlock Pixel with Botpoison for multi-layer spam protection. Combine behavioral detection with challenge-based verification.

This guide shows how to combine SpamBlock Pixel with Botpoison for multi-layer spam protection. This approach combines behavioral detection (SpamBlock) with challenge-based verification (Botpoison).

Note: You can use any backend endpoint. The SpamBlock Forms endpoint (https://api.spamblock.io/f/{form_id}) is shown as an example of our hosted form solution. Learn more about Forms or use your own backend endpoint.

HTML/JavaScript Example

Here's a basic example using vanilla HTML and JavaScript:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Contact Form</title>
  
  <!-- Load SpamBlock Pixel -->
  <script src="https://pixel.spamblock.io/latest.js" defer></script>
  
  <!-- Load Botpoison -->
  <script src="https://unpkg.com/@botpoison/browser"></script>
</head>
<body>
  <form id="contact-form" action="#" method="POST">
    <label for="name">Name</label>
    <input id="name" name="name" type="text" required />

    <label for="email">Email Address</label>
    <input id="email" name="email" type="email" required />

    <label for="message">Message</label>
    <textarea id="message" name="message" required></textarea>

    <button type="submit">Send</button>
  </form>

  <script>
    window.addEventListener("DOMContentLoaded", async function() {
      const form = document.getElementById("contact-form");
      
      // Initialize Botpoison
      const botpoison = new Botpoison({
        publicKey: "YOUR_BOTPOISON_PUBLIC_KEY",
      });

      // Listen for allowed submissions from SpamBlock
      form.addEventListener("spamblock:allowed", async function(event) {
        event.preventDefault();

        const formData = new FormData(event.target);

        try {
          // Get Botpoison challenge solution
          const { solution } = await botpoison.challenge();

          // Add Botpoison solution to form data
          formData.append("botpoison-solution", solution);

          const response = await fetch("https://api.spamblock.io/f/{form_id}", {
            method: "POST",
            body: formData
          });

          if (response.ok) {
            alert("Submission successful!");
            form.reset();
          } else {
            alert("There was an error submitting the form.");
          }
        } catch (error) {
          if (error.message && error.message.includes("challenge")) {
            alert("Please complete the Botpoison challenge.");
          } else {
            alert("Network error. Please try again.");
          }
          console.error("Error:", error);
        }
      });
    });
  </script>
</body>
</html>

Framework Integration

The same pattern works in frameworks. Reference these examples for framework-specific implementations:

The key is to:

  1. Initialize Botpoison in your component
  2. Listen for the spamblock:allowed event
  3. Call botpoison.challenge() to get the challenge solution
  4. Include the solution in your form submission

How It Works

The spam handling flow with both services:

  1. User submits form
  2. SpamBlock Pixel intercepts submission and scores it
  3. If spam: submission blocked by SpamBlock, spamblock:allowed event not fired
  4. If allowed: spamblock:allowed event fired
  5. Botpoison challenge is generated
  6. User completes Botpoison challenge
  7. Submission sent to backend with both SpamBlock validation and Botpoison solution
  8. Backend verifies both before processing

When to Use It

Use this approach when:

  • You want multiple layers of spam protection
  • You're already using Botpoison in your project
  • You need defense-in-depth against sophisticated bots
  • You want to combine different detection methods

Important Notes

  • Replace API key: Replace YOUR_BOTPOISON_PUBLIC_KEY with your actual Botpoison public key
  • Backend verification: Always verify the Botpoison solution on your backend
  • Performance: Running multiple spam checks adds latency, consider if both are needed
  • Error handling: Botpoison challenges can fail, always wrap in try/catch

Common Mistakes

  1. Not waiting for pixel - Make sure the pixel script loads before form submission
  2. Ignoring events - Listen for spamblock:allowed event to know when submission is safe
  3. Missing Botpoison key - Replace YOUR_BOTPOISON_PUBLIC_KEY with your actual Botpoison public key
  4. Not handling Botpoison errors - Botpoison challenges can fail, always wrap in try/catch
  5. Skipping backend verification - Always verify the Botpoison solution on your backend
  6. Performance concerns - Running multiple spam checks adds latency, consider if both are needed
  7. Script loading order - Ensure both SpamBlock Pixel and Botpoison scripts load before form interaction

Learn More