#WordPress Plugin

The Datalumo WordPress plugin connects your WordPress site to Datalumo. Sync your content, enhance your native search with AI-powered results, embed chatbots, and add search widgets - all from a single settings page.

#Requirements

• WordPress 6.0 or later
• PHP 8.1 or later
• An active Datalumo account

#Installation

1. Download the plugin ZIP from the top of this page
2. In WordPress, go to Plugins > Add New > Upload Plugin
3. Upload the ZIP file and click Install Now
4. Activate the plugin

#Automatic Updates

The plugin checks for updates from Datalumo automatically. When a new version is available you'll see an update notification in your WordPress admin, just like any other plugin. Updates can be installed with one click from the Plugins page.

#Configuration

After activation, go to Settings > Datalumo. The settings page has four tabs.

#API Connection

Enter the API token from your Datalumo account settings and click Save & Test Connection. All other tabs are disabled until a valid API token is configured.

#Content Sync

Content Sync pushes your WordPress posts to a Datalumo collection so they can be searched and used for AI features.

• Click Add Sync to create a new sync configuration
• Select a target Collection (or create one inline)
• Choose which Post Types to include
• Click Sync Now to run an initial bulk sync

You can create multiple syncs to send different post types to different collections. Progress is shown in real time while a sync is running.

Once a sync is configured, content is kept up to date automatically. Publishing or updating a post syncs it to Datalumo. Trashing or deleting a post removes it.

#Chatbot

Enable the chatbot toggle and select an integration to embed a Datalumo chatbot on your site. The chatbot widget is automatically injected on every page.

You can also place the chatbot manually using the shortcode:

[datalumo_chat]

#Enhanced Native Search

When enabled, the plugin replaces the default WordPress search with AI-powered results from Datalumo. If the Datalumo API is unavailable, search falls back to the default WordPress behavior automatically.

Settings:

#How it works

The plugin intercepts the main WordPress search query before it hits the database and sends it to Datalumo instead. Datalumo returns matching entries ranked by semantic similarity. The plugin maps those back to local posts and returns them in the correct order.

For AI summaries, the plugin loads a small script that fetches the summary asynchronously via AJAX, so it does not slow down the initial page load.

#Favouring recent posts

If you want recent posts to rank a little higher without sacrificing the semantic match, add a recency boost to the search request. Point it at your published_at meta field and leave the defaults:

{
  "query": "user's search term",
  "boost": [
    { "field": "published_at", "type": "recency", "strength": "medium" }
  ]
}

See the Search Ranking guide for all available boost types and how they compose.

#Click Tracking

When enhanced search is active, the plugin loads the Datalumo SDK to track which search results users click on. This data is available in your Datalumo analytics dashboard.

#Search Widget

You can embed a standalone Datalumo search box anywhere using the shortcode:

[datalumo_search]

This renders a search widget powered by your configured search box integration.

#Advanced: Programmatic Search Integration

For developers building custom themes or templates, the plugin exposes a PHP API to use Datalumo search on any WP_Query - not just the main search.

#Custom Query with Datalumo

Pass the datalumo flag to any WP_Query to route it through Datalumo:

$query = new WP_Query([
    'datalumo' => true,
    's'        => 'your search term',
]);

if ($query->have_posts()) {
    while ($query->have_posts()) {
        $query->the_post();
        // Render results
    }
    wp_reset_postdata();
}

This bypasses the is_main_query() check that normally limits Datalumo to the main search. The post type filter setting does not apply to explicit datalumo queries - you have full control.

#Using a Different Integration

By default, custom queries use the integration configured in the plugin settings. Override it with datalumo_integration:

$query = new WP_Query([
    'datalumo'             => true,
    'datalumo_integration' => 'your-integration-id',
    's'                    => 'your search term',
]);

This lets you target different collections from different parts of your site.

#Checking if a Summary is Available

After the query runs, check the datalumo_summarisable property to determine whether an AI summary can be generated for the results:

if (!empty($query->datalumo_summarisable)) {
    // A summary is available for this query
}

#Enqueuing the AI Summary

Use datalumo_enqueue_summary() to load the AI summary via AJAX on any page. The summary loads asynchronously so it does not block page rendering.

datalumo_enqueue_summary('your search term', [
    'integration_id' => 'your-integration-id', // optional, defaults to plugin setting
    'selector'       => '#my-summary-container', // CSS selector for placement
    'position'       => 'prepend', // 'prepend' or 'append'
    'locale'         => 'en', // optional, defaults to site locale
]);

Combine it with the summarisable check for the best experience - this way the summary skeleton only appears when a summary is actually available:

$query = new WP_Query([
    'datalumo'             => true,
    'datalumo_integration' => 'your-integration-id',
    's'                    => $searchTerm,
]);

if (!empty($query->datalumo_summarisable)) {
    datalumo_enqueue_summary($searchTerm, [
        'integration_id' => 'your-integration-id',
        'selector'       => '#my-summary',
    ]);
}

#Click Tracking

When using datalumo_enqueue_summary(), click tracking is included automatically. If you only need click tracking without a summary, use datalumo_enqueue_click_tracking():

datalumo_enqueue_click_tracking(
    'your-integration-id', // optional, defaults to plugin setting
    '#my-results-container' // CSS selector for the results container
);

To disable click tracking when enqueuing a summary:

datalumo_enqueue_summary('search term', [
    'click_tracking' => false,
]);

#Full Example

A complete custom search page using the Datalumo API with an AI summary and click tracking:

<?php
$searchTerm = sanitize_text_field($_GET['q'] ?? '');

if ($searchTerm) {
    $query = new WP_Query([
        'datalumo'             => true,
        'datalumo_integration' => 'your-integration-id',
        's'                    => $searchTerm,
    ]);

    if (!empty($query->datalumo_summarisable)) {
        datalumo_enqueue_summary($searchTerm, [
            'integration_id' => 'your-integration-id',
            'selector'       => '#search-summary',
        ]);
    }

    datalumo_enqueue_click_tracking('your-integration-id', '#search-results');
}
?>

<div id="search-summary"></div>

<div id="search-results">
    <?php if ($query->have_posts()): ?>
        <?php while ($query->have_posts()): $query->the_post(); ?>
            <article>
                <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
                <?php the_excerpt(); ?>
            </article>
        <?php endwhile; ?>
        <?php wp_reset_postdata(); ?>
    <?php else: ?>
        <p>No results found.</p>
    <?php endif; ?>
</div>

#Function Reference

#datalumo_enqueue_summary(string $query, array $options = []): void

Enqueues the AI summary assets (CSS, JS) and configures the AJAX-powered summary.

Options:

#datalumo_enqueue_click_tracking(?string $integrationId = null, string $container = '...'): void

Enqueues the Datalumo SDK for click tracking on search results.

Parameters:

#Uninstallation

When the plugin is deleted through the WordPress admin, all plugin data is removed from the database. This includes the API key, sync configurations, sync states, and all settings. Pending background tasks are cancelled.

Content already synced to Datalumo is not affected - it remains in your Datalumo collections.