Getting started overview

Integrating Botd into an application involves a few core steps to enable its bot detection capabilities. The process typically begins with account creation and the retrieval of necessary API credentials. Following this, developers integrate either the Botd JavaScript agent into their client-side application or make direct calls to the Botd Server API from their backend, depending on the specific use case and architecture. The JavaScript agent collects signals directly from the user's browser, while the server API allows for explicit requests to evaluate suspicious activity.

Botd offers a free tier that includes 10,000 requests per month, which can be used for initial setup and testing without incurring costs. Paid plans are available for higher volumes, starting at $10 per month for 100,000 requests. This tiered pricing model allows for scalability as application needs grow. The primary goal of a getting started process is to achieve a working implementation where Botd successfully identifies a bot and returns a detection signal, enabling subsequent custom logic for mitigation.

Here’s a quick reference for the Botd getting started process:

Step What to do Where
1. Create Account Register for a Botd account. Botd homepage
2. Get API Key Locate and copy your public API key from the dashboard. Botd Dashboard > API Keys
3. Install JavaScript Agent Add the Botd JavaScript snippet to your web pages. HTML <head> or build system
4. Make First Request (Client-side) Initialize the agent and call botd.detect(). Client-side JavaScript code
5. Make First Request (Server-side) Send a POST request to the Botd API with relevant data. Backend code (e.g., Node.js, Python, Java)
6. Interpret Response Examine the botdStatus and botdVerdict fields. Botd API response documentation

Create an account and get keys

To begin using Botd, the initial step is to create an account on the official Botd website. This process typically involves providing an email address and setting up a password. Upon successful registration, users are directed to their Botd dashboard.

Within the dashboard, a critical piece of information required for integration is the Public API Key. This key is used by the client-side JavaScript agent to authenticate requests to the Botd service. It is distinct from secret API keys, which are typically used for server-to-server communication and should be kept confidential. For client-side integration, the public key is embedded directly in the web application's code.

Navigate to the 'API Keys' section within your Botd dashboard to locate and copy this key. It will be a string of alphanumeric characters. This key will be referenced when initializing the Botd JavaScript agent or when making direct API calls from your application. Ensure this key is accessible for the next steps of the integration process.

Your first request

Botd offers two primary methods for making a first request: via its client-side JavaScript agent or directly through its server-side API. The choice depends on where you want to perform the initial bot detection and what level of detail you require.

Client-side Integration (JavaScript Agent)

The most common method for web applications is to integrate the Botd JavaScript agent. This agent collects browser signals and sends them to Botd for analysis, returning a bot detection verdict directly to the client.

Step 1: Include the JavaScript Agent

Add the Botd JavaScript snippet to the <head> section of your HTML pages. Replace YOUR_PUBLIC_API_KEY with the key obtained from your Botd dashboard.

<script
  async
  src="https://cdn.botd.io/botd.min.js"
  botd-token="YOUR_PUBLIC_API_KEY"
  onload="initBotd()"
></script>

Step 2: Initialize and Detect

Create a JavaScript function, for example, initBotd(), that will be called once the Botd agent has loaded. Inside this function, initialize Botd and then call the detect() method.

async function initBotd() {
  if (window.Botd) {
    const botd = await Botd.load();
    const result = await botd.detect();
    console.log('Botd Detection Result:', result);

    // Example: Check if it's a bot
    if (result.bot.result === 'bad') {
      console.warn('Bot detected! Action required.');
      // Implement your blocking or mitigation logic here
    } else {
      console.log('Human user detected.');
    }
  }
}

The result object will contain a bot property with a result field indicating the detection outcome (e.g., 'notDetected', 'bad', 'good'). For detailed information on the response structure, refer to the Botd API reference.

Server-side Integration (Botd Server API)

For scenarios where bot detection needs to occur on the server or for applications without a client-side JavaScript component (e.g., mobile apps, IoT devices), the Botd Server API can be used directly. This requires sending specific signals to the Botd endpoint from your backend.

Step 1: Obtain a Server API Key

While the client-side uses a public key, server-side interactions typically require a secret API key for secure authentication. Obtain this from your Botd dashboard if available, or ensure your public key is used securely if no secret key is provided for server interaction. For client-side, the public key is sufficient.

Step 2: Make a POST Request

Send a POST request to the Botd API endpoint, including relevant headers and a JSON payload. The payload should contain data points that help Botd make a detection. For a minimal first request, you might include an IP address or user agent string.

const BOTD_API_KEY = 'YOUR_PUBLIC_API_KEY'; // Or your secret server key if applicable
const BOTD_API_URL = 'https://api.botd.io/api/v1/detect';

async function detectServerSideBot() {
  try {
    const response = await fetch(BOTD_API_URL, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': BOTD_API_KEY,
      },
      body: JSON.stringify({
        // Minimal example; ideally include more context
        ipAddress: 'YOUR_USER_IP_ADDRESS',
        userAgent: 'YOUR_USER_AGENT_STRING',
        // Add other relevant signals as per Botd documentation
      }),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Botd Server API Detection Result:', data);

    if (data.bot.result === 'bad') {
      console.warn('Bot detected server-side! Implement server-side blocking.');
    } else {
      console.log('Human user detected server-side.');
    }

  } catch (error) {
    console.error('Error during server-side bot detection:', error);
  }
}

detectServerSideBot();

Replace YOUR_USER_IP_ADDRESS and YOUR_USER_AGENT_STRING with actual data from the incoming client request. The Botd Server API documentation provides a comprehensive list of parameters for detection.

Common next steps

After successfully making your first Botd detection, several common next steps can enhance your bot protection strategy:

  1. Implement Blocking Logic: Based on the botdVerdict (or bot.result in the latest API), implement server-side or client-side logic to block, challenge, or rate-limit suspicious requests. This might involve redirecting bots, presenting CAPTCHAs, or denying access to specific API endpoints.
  2. Integrate with Backend: For client-side integrations, send the Botd detection result to your backend. This allows your server to make authoritative decisions, log bot activity, and apply server-side mitigations, such as those described by Cloudflare's bot management strategies.
  3. Monitor and Analyze: Utilize the Botd dashboard to monitor detection trends, review flagged requests, and understand the types of bots targeting your application. This data can inform adjustments to your security policies.
  4. Configure Custom Rules: Botd may allow for custom rule creation or fine-tuning of detection thresholds. Explore these options in your dashboard to tailor bot detection to your application's specific needs and threat landscape.
  5. Explore Advanced Features: Investigate other Botd features such as detailed bot categories, risk scores, and integration with other security tools.
  6. Review SDKs and Libraries: If you are using a specific framework or language, check for official or community-contributed SDKs that might simplify integration beyond the basic JavaScript agent or raw API calls. Botd currently provides a JavaScript SDK.
  7. Set up Webhooks or Alerts: Configure notifications to alert you when high volumes of bot activity are detected, enabling a proactive response to attacks.

Troubleshooting the first call

When setting up Botd for the first time, you might encounter issues. Here are common problems and troubleshooting steps:

  • Invalid API Key:
    • Symptom: Errors indicating authentication failure or no detection results.
    • Solution: Double-check that the botd-token in your JavaScript snippet or x-api-key header for server-side requests exactly matches the Public API Key from your Botd dashboard. Ensure there are no leading or trailing spaces.
  • JavaScript Agent Not Loading:
    • Symptom: window.Botd is undefined, or initBotd() is not called.
    • Solution: Verify that the <script> tag for botd.min.js is correctly placed in the <head> and that the async attribute is present. Check your browser's developer console for network errors (e.g., 404 for the script) or JavaScript errors that might prevent execution. Ensure onload="initBotd()" is correctly specified and that the initBotd function exists in the global scope or is otherwise accessible.
  • No Detection Result (Client-side):
    • Symptom: The botd.detect() call completes, but the result.bot.result is always 'notDetected' even for known bots.
    • Solution: Ensure your test environment is not blocking necessary network requests to Botd's detection servers. Ad blockers or privacy extensions can sometimes interfere. Try testing with a clean browser profile. Also, verify that the browser environment provides sufficient signals (e.g., not running in a highly restrictive headless browser that might suppress legitimate signals).
  • No Detection Result (Server-side):
    • Symptom: Server API returns generic error or no bot detection.
    • Solution: Confirm that your server-side code is sending the correct Content-Type: application/json header and that the JSON body is well-formed. Ensure you are including relevant data like ipAddress and userAgent in the request payload as these are critical for detection. Consult the Botd API reference documentation for required and optional parameters.
  • CORS Errors:
    • Symptom: Browser console shows Cross-Origin Resource Sharing errors when the JavaScript agent attempts to communicate with Botd.
    • Solution: Botd's CDN and API are configured for CORS. If you encounter these, it might indicate an unusual network configuration, a misconfigured proxy, or a very restrictive Content Security Policy (CSP) on your site. Review your CSP to ensure it allows connections to cdn.botd.io and api.botd.io.