Set up AI Chatbot tracking with the HTTP Tracking API

AI chatbots retrieve website content through HTTP requests and typically do not execute client-side JavaScript embedded in the page. This means their activity cannot be captured using the standard Matomo JavaScript tracker (matomo.js).

If your server, reverse proxy, CDN or other infrastructure can detect these requests, you can send the request details to Matomo using the HTTP Tracking API. Matomo processes valid AI chatbot requests in a dedicated no-visit mode, so they do not create visits, sessions or attribution data.

This guide explains the parameters required to record AI chatbot activity through the HTTP Tracking API and provides practical implementation examples.

A custom integration is required

The Matomo HTTP Tracking API does not monitor requests arriving at your website nor does it install tracking automatically. An integration must identify AI chatbot requests and send the relevant activity to Matomo.

Choose an integration for your infrastructure

Your website infrastructure determines where the integration runs, for example in a Cloudflare Worker, an Amazon CloudFront function, application middleware, a reverse proxy, a web-server log-processing pipeline or a separate service written in a server-side language such as Node.js, PHP or Python.

If your website uses one of the following platforms, use its dedicated setup guide:

• Set up AI Chatbot tracking with Cloudflare
• Set up AI Chatbot tracking with Amazon CloudFront
• Set up AI Chatbot tracking with WordPress

Continue with this HTTP Tracking API guide below to use a custom integration where your infrastructure can detect incoming AI chatbot requests.

What the custom integration must do

A developer must create the integration in a system with access to the incoming requests. When using the HTTP Tracking API, the custom integration must:

• Identify AI chatbot requests.
• Collect the User-Agent string and requested URL.
• Send a tracking request to the matomo.php endpoint of your Matomo instance.
• Include the required AI chatbot tracking parameters.
• Optionally include additional chatbot telemetry, such as the HTTP status code, bytes transferred or server processing time.

This custom integration is only required to capture server-side AI chatbot requests.

You can continue using the Matomo JavaScript tracker (matomo.js) for browser-based tracking. The custom HTTP API integration records server-side AI chatbot requests in no-visit mode.

How HTTP API chatbot tracking works

Your custom integration runs in a system that can inspect incoming website requests or the resulting access logs. It collects the relevant details and sends a separate tracking request to your Matomo tracking endpoint.

The process works as follows:

1. When preparing a response to a user’s question, an AI chatbot may discover a relevant content from your website and send an HTTP request to retrieve the webpage, document or other resource.
2. Your custom integration inspects incoming requests or access log entry and reads information such as the User-Agent string and requested URL.
3. When the User-Agent matches a supported AI chatbot identifier, the integration constructs a separate tracking request containing the original request details, Matomo website ID and required tracking parameters. It then sends this request to matomo.php.
4. Matomo independently validates the submitted User-Agent. If Matomo recognises it as a supported AI chatbot, it stores the request in no-visit mode and the activity then becomes available in the AI chatbot reports once processed.
5. If Matomo does not recognise it as a supported AI chatbot, it discards only that tracking request. The request does not create a visit or action and does not appear in the AI chatbot reports. Other browser-based tracking requests are not affected.

Send an AI chatbot tracking request to Matomo

A developer must implement this process to record requests for your website. When the integration runs as part of the website’s request flow, it should do the following:

• Reads the request’s User-Agent header and requested URL.
• Checks whether the User-Agent matches a supported AI chatbot identifier.
• Constructs a separate HTTP request containing the configured Matomo tracking parameters.
• Sends the tracking request to the matomo.php endpoint of your Matomo instance. All string values must be URL-encoded before they are sent to Matomo. For example:
  https://example.com/docs/intro becomes https%3A%2F%2Fexample.com%2Fdocs%2Fintro

Required AI chatbot tracking parameters

Each request sent to matomo.php must provide parameters to record information for Matomo to identify the website, classify the AI chatbot, and record the requested resource. You can also send optional telemetry using additional parameters, see Optional Bot info in the API documentation.

After your integration identifies a supported AI chatbot, it must send the original User-Agent and requested resource to the matomo.php endpoint.

The following examples send the same webpage request using cURL, PHP, Python and Node.js and send requests directly to demonstrate how the request works. Replace the values for your Matomo instance:

• https://your-matomo-domain.example/matomo.php with your Matomo tracking endpoint.
• 1 with your Matomo website ID.
• ChatGPT-User/1.0 with the full User-Agent from the incoming request. Your integration would replace <user-agent> and <requested-url> with values from the original AI chatbot request.
• https://example.com/docs/intro with the resource requested by the AI chatbot.
• The examples use the url parameter. To record a file or document request, use download instead.

In production, consider sending them asynchronously or through a queue so a slow or unavailable Matomo endpoint does not delay responses from your website.

Example: cURL

Use this example to send a test request from a terminal:

curl --get 'https://your-matomo-domain.example/matomo.php' \
  --data-urlencode 'idsite=1' \
  --data-urlencode 'rec=1' \
  --data-urlencode 'recMode=1' \
  --data-urlencode 'ua=ChatGPT-User/1.0' \
  --data-urlencode 'url=https://example.com/docs/intro'

The --data-urlencode options ensure that values such as the User-Agent and requested URL are correctly encoded.

Example: PHP

This example requires the PHP cURL extension:

<?php

$matomoTrackingUrl = 'https://your-matomo-domain.example/matomo.php';

$parameters = [
    'idsite'  => 1,
    'rec'     => 1,
    'recMode' => 1,
    'ua'      => 'ChatGPT-User/1.0',
    'url'     => 'https://example.com/docs/intro',
];

$trackingUrl = $matomoTrackingUrl
    . '?'
    . http_build_query(
        $parameters,
        '',
        '&',
        PHP_QUERY_RFC3986
    );

$curl = curl_init($trackingUrl);

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 2,
    CURLOPT_TIMEOUT        => 5,
]);

$response = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

if ($response === false || $statusCode < 200 || $statusCode >= 300) {
    throw new RuntimeException(
        'Unable to send AI chatbot activity to Matomo: '
        . curl_error($curl)
    );
}

curl_close($curl);

In a working integration, populate ua and url from the incoming website request rather than using the example values.

Example: Python

This example uses modules from the Python standard library:

from urllib.parse import urlencode
from urllib.request import urlopen

matomo_tracking_url = (
    "https://your-matomo-domain.example/matomo.php"
)

parameters = {
    "idsite": 1,
    "rec": 1,
    "recMode": 1,
    "ua": "ChatGPT-User/1.0",
    "url": "https://example.com/docs/intro",
}

tracking_url = (
    f"{matomo_tracking_url}?{urlencode(parameters)}"
)

with urlopen(tracking_url, timeout=5) as response:
    if not 200 <= response.status < 300:
        raise RuntimeError(
            f"Matomo returned HTTP {response.status}"
        )

In a working integration, pass the User-Agent and requested URL from your application, middleware or access-log processor into parameters.

Example: Node.js

This example uses the built-in fetch() API available in current Node.js releases:

const matomoTrackingUrl =
  'https://your-matomo-domain.example/matomo.php';

const parameters = new URLSearchParams({
  idsite: '1',
  rec: '1',
  recMode: '1',
  ua: 'ChatGPT-User/1.0',
  url: 'https://example.com/docs/intro',
});

async function sendChatbotActivity() {
  const trackingUrl =
    `${matomoTrackingUrl}?${parameters.toString()}`;

  const response = await fetch(trackingUrl);

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

sendChatbotActivity().catch(console.error);

In a working integration, populate ua and url from the incoming request or processed access-log entry.

Verify AI Chatbot tracking in Matomo

After sending a test request using one of the examples above, you can check the tracking setup is correctly configured.

1. Go to AI Assistants > AI Chatbot Real-time.
2. Confirm that the test request appears with the expected AI chatbot and requested resource.
   
3. If you see a No data collected message, you will need to review your configuration.
   
4. AI chatbot tracking will appear in reports once AI chatbot activity is recorded.

This integration is suitable when you control the request flow or can process server, proxy or CDN access logs. Requests sent through a custom HTTP API integration follow the same no-visit tracking rules as the Cloudflare and Amazon CloudFront integrations.

Read more about AI chatbot data retention and filtering and exclusions.