Set up AI Chatbot tracking with Cloudflare or Amazon CloudFront

Cloud On-Premise

AI chatbots increasingly access websites through edge and server-side infrastructure such as CDNs and reverse proxies. Matomo supports AI chatbot telemetry through the existing HTTP Tracking API, allowing this traffic to be ingested separately from human website analytics. AI chatbot requests are processed in a dedicated no-visit mode, meaning they do not create visits, sessions, or attribution data.

This guide explains how AI chatbot telemetry works in Matomo and how to set up telemetry ingestion in edge environments such as Cloudflare and Amazon CloudFront.

How AI chatbot telemetry works in Matomo

AI chatbot telemetry uses the standard Matomo tracking endpoint (matomo.php) but follows a dedicated processing path. When a request is detected from an AI chatbot:

  • No visitor or session is created.
  • No visit attribution logic is executed.
  • No data is written to visit-related tables such as log_visit or log_link_visit_action.
  • Telemetry data is stored in dedicated chatbot telemetry tables.
  • URLs are resolved through log_action without performing visit lookups.

This behaviour is automatic and does not require additional configuration once telemetry requests are sent.

Supported AI chatbots and detection rules

Matomo detects AI chatbots based on User-Agent substring matching to ensure AI chatbot traffic is always processed separately from human visits. A request is classified as a chatbot when its User-Agent contains one of the following substrings (minimum supported list):

ChatGPT-User
MistralAI-User
Gemini-Deep-Research
Claude-User
Perplexity-User
GoogleAgent
NovaAct

Detection cannot be overridden and requests identified as AI chatbots are always processed in no-visit mode.

Set up AI Chatbot tracking

AI chatbot reports only collect data after setting up chatbot tracking. If you open an AI chatbot report and see a No data collected message, you will need to configure chatbot telemetry for your environment.

  1. Where an AI chatbot report shows no data has been collected, click the link Set up AI Chatbot tracking now.
    ai report no data message
  2. Choose your AI Chatbot tracking method and follow the on-screen instructions in Matomo to guide you through the installation:

Install with Cloudflare

This option installs AI chatbot telemetry at the Cloudflare edge using a Cloudflare Worker. The Worker runs inline with requests and sends AI chatbot telemetry to Matomo without affecting request handling.

The tracker code is maintained externally. Follow the linked repository readme for the latest setup and deployment instructions.

  1. Deploy the Cloudflare Worker (Node.js) and configure your Matomo URL and Matomo site ID.
  2. Attach the Worker to your zone or route so it runs inline with requests.
  3. Verify that chatbot hits appear in the AI chatbot reports.

What the integration does

  • An AI chatbot requests a URL on your site.
  • The Cloudflare Worker runs and forwards the request to your origin server (normal behaviour).
  • It sends a telemetry hit to matomo.php asynchronously, for example:
https://your-matomo.com/matomo.php?idsite=1
  &rec=1
  &recMode=1
  &url=https://example.com/page
  &ua=ChatGPT-User
  &source=Cloudflare
  ...
  • Your origin server returns the response to the AI chatbot.
  • Matomo receives the telemetry via the HTTP Tracking API, processes it in no-visit mode and stores it in the dedicated telemetry tables.

Install with Amazon CloudFront

Use this option if your site is served through Amazon CloudFront and AI chatbot requests are logged at the CDN level. This integration uses AWS Lambda together with Amazon CloudFront to process access logs and send AI chatbot telemetry to Matomo.

The tracker code is maintained externally. Always follow the repository readme for current setup and deployment instructions.

  1. Deploy the Lambda function (Node.js) and configure your Matomo URL and Matomo site ID.
  2. Attach an S3 trigger for Amazon CloudFront access log objects (for example, ObjectCreated events on .gz log files).
  3. Verify that chatbot hits appear in the AI chatbot reports.

What the integration does

  • An AI chatbot requests a URL on your site.
  • Amazon CloudFront serves the request and writes an access log entry to your configured S3 log bucket.
  • The AWS Lambda function is triggered by the new log object, then reads and processes the Amazon CloudFront access logs.
  • It identifies supported AI chatbot User-Agents, builds telemetry hits, and sends them in batches. Lambda sends a single HTTP request to matomo.php with a JSON payload that contains multiple tracking requests, for example:
POST https://your-matomo.com/matomo.php
{
  "requests": [
    "?idsite=1&rec=1&recMode=1&url=https://example.com/page-a&ua=ChatGPT-User&source=CloudFront",
    "?idsite=1&rec=1&recMode=1&url=https://example.com/page-b&ua=Perplexity-User&source=CloudFront"
  ]
}

Verify tracking is enabled

AI chatbot traffic is not user-initiated, so data may not appear immediately after setup. After AI chatbots access your site and Matomo receives valid chatbot telemetry, the No data message on reports disappears automatically. To verify that tracking is enabled:

  1. Open the relevant AI chatbot reports in Matomo > AI Assistants.
    matomo ai chatbot report
  2. Confirm that the No data message no longer appears.
  3. Check that requests from supported AI chatbots are listed.

Data retention

AI chatbot telemetry is stored as raw log data in Matomo. This data follows the same retention and cleanup rules as other raw tracking logs. When the Delete old raw data from the database setting is enabled, Matomo automatically removes AI chatbot telemetry after the configured retention period.

  • No visit or aggregated data is created from this telemetry.
  • No additional configuration is required to enable cleanup.
  • Deletion affects all stored AI chatbot telemetry.

This behaviour applies to both Matomo Cloud and Matomo On-Premise instances.

Filtering and exclusions

AI chatbot telemetry is request-based and can generate large volumes of data. Applying filtering at the edge helps reduce noise and keeps telemetry focused on meaningful requests.

Common exclusions include:

  • /robots.txt
  • health check endpoints
  • internal or diagnostic URLs

Filtering should be applied before sending telemetry to Matomo, for example in your Cloudflare Worker or Amazon CloudFront Lambda logic. This ensures that only relevant AI chatbot requests are recorded and stored.

When to use the HTTP Tracking API directly

If you need a custom integration, or you are not using Cloudflare, CloudFront, or WordPress, you can send AI chatbot telemetry directly using the HTTP Tracking API.

  1. Start with the Tracking API documentation to understand how to construct tracking requests.
  2. Then refer to the Tracking Bots API reference for the supported parameters and processing behaviour specific to AI chatbot telemetry.

This approach is suitable when you control the request flow directly and tracking is implemented in server-side code or middleware. Tracking requests sent this way follow the same no-visit tracking rules as the Cloudflare and CloudFront integrations. Edge or CMS integrations are not applicable.

Previous FAQ: What are AI Assistants in Matomo