> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siftly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress Plugin

> Install the Siftly AI Bot Tracker plugin to log AI crawler visits on your WordPress site.

<Frame>
  <img src="https://mintcdn.com/siftly/4tAGLoP6M7hAzxgx/images/bot-traffic-flow.svg?fit=max&auto=format&n=4tAGLoP6M7hAzxgx&q=85&s=4b21b43aea4908955e324df7731fa918" alt="AI bot traffic detection — WordPress plugin intercepts AI crawler requests" className="rounded-xl" width="900" height="240" data-path="images/bot-traffic-flow.svg" />
</Frame>

## Installation

<Steps>
  <Step title="Download the Plugin">
    In the Siftly dashboard, go to **Traffic → Connect** and select **WordPress**. Click the **Download Siftly AI Bot Tracker** button.

    The downloaded zip already contains your Organisation ID and API endpoint — no manual configuration required.
  </Step>

  <Step title="Upload to WordPress">
    1. Log in to your WordPress admin panel.
    2. Go to **Plugins → Add New → Upload Plugin**.
    3. Click **Choose File**, select the `siftly-ai-bot-tracker.zip` file, and click **Install Now**.
    4. After installation completes, click **Activate Plugin**.

    You will be redirected to the **Settings → Siftly** page automatically.
  </Step>

  <Step title="Verify the Connection">
    On the **Settings → Siftly** page, confirm that the **API Endpoint URL** and **Organisation ID** are pre-filled, then scroll down and click **Send Test Event**.

    A green success banner confirms everything is working.

    <Tip>
      If you need to change the Organisation ID later (e.g. switching to a different Siftly org), update it on this settings page and click **Save Settings**.
    </Tip>
  </Step>
</Steps>

## How It Works

The plugin:

1. **Captures** every public page visit and checks the User-Agent against the AI bot list.
2. **Queues** bot events in a lightweight local database table.
3. **Sends** queued events to the traffic-ingest-service in batches every 5 minutes via WP-Cron.

This means the plugin never slows down your page loads — tracking happens entirely in the background.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Circuit breaker is tripped">
    The plugin automatically pauses sending after 5 consecutive failures to avoid hammering a temporarily unavailable endpoint. It resumes after 5 minutes.

    To reset immediately, go to **Settings → Request Tracker** and click **Reset Circuit Breaker**.
  </Accordion>

  <Accordion title="No events appearing in Siftly">
    1. Go to **Settings → Siftly** and confirm the **Organisation ID** and **API Endpoint URL** are filled in. If you downloaded the plugin from the Siftly dashboard, both should be pre-filled.
    2. Confirm the **API Endpoint URL** ends with `/log/wordpress`.
    3. Click **Send Test Event** to verify connectivity.
    4. Check WP-Cron is running — some hosts disable WP-Cron. You may need to trigger it with a real cron job:
       ```bash theme={null}
       */5 * * * * curl https://yoursite.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1
       ```
  </Accordion>

  <Accordion title="I see events but the Organisation ID is wrong">
    Go to **Settings → Siftly**, clear the Organisation ID field, paste the correct UUID from the Siftly dashboard, and click **Save Settings**.
  </Accordion>
</AccordionGroup>