Datalumo
Docs · WordPress ▾
View as Markdown →

WordPress plugin

The Datalumo plugin connects a WordPress site to your knowledge base without any code. It keeps your posts and pages in sync, adds a chat widget and a search box, and can serve WordPress' own search results from Datalumo's ranking.

Everything is configured under Settings → Datalumo, in five tabs: Connection, Content sync, Chatbot, Search box, and Enhanced search.

Feature What it does
Content sync Pushes published content to a source, and follows edits, unpublishes, and deletes
Chatbot A floating assistant on every page, or inline with a shortcode
Search box A Datalumo search box anywhere, with the [datalumo_search] shortcode
Enhanced search Your theme's search page, ranked by Datalumo, with an optional AI summary
Visitor identity Logged-in users pick up their previous conversations

Requirements: WordPress 6.0 or newer, PHP 8.1 or newer.

#Install

  1. Download the latest release zip from github.com/datalumo/wordpress.
  2. In WordPress, go to Plugins → Add New → Upload Plugin, pick the zip, and activate.
  3. Open Settings → Datalumo.

The plugin checks that GitHub repository for new versions, so later updates show up on your Plugins screen like any other plugin.

#Connect your account

In Datalumo, before you start:

  1. Create a source of type API. This is the container your WordPress content lands in.
  2. Create an API key with the pages.write permission (see Authentication). You can limit the key to that one source.
  3. Copy your organisation ID from the same page. It is a long id, not your organisation name.

Then, on the Connection tab, paste the organisation ID and the API key and press Connect & test. A successful test confirms the key and remembers your sources, so the rest of the settings can offer them in dropdowns.

The key is stored in your WordPress database and only ever used server to server. It is never printed into a page.

Self-hosting Datalumo? Change the Datalumo URL field to your own install, or set it in wp-config.php:

define('DATALUMO_API_URL', 'https://datalumo.example.com');

#Sync your content

On the Content sync tab, pick a source and tick the post types that belong in it (posts, pages, products, or any custom type your site registers). Save, then press Sync now for the first full run.

After that, syncing takes care of itself:

In WordPress In Datalumo
A post is published The page is created or updated
A published post is edited The page is updated
A post is unpublished or trashed The page is removed
A post is deleted The page is removed

Only published content of the post types you ticked is synced. Autosaves and revisions are ignored. All of this runs in the background, so editors never wait on the network, and a failed push is retried.

#What a page looks like

Page field Comes from
Title Post title
Content Post content, with blocks rendered and shortcodes stripped
URL Permalink
Reference Post ID, so re-syncing updates instead of duplicating
Details Post type, categories, tags, author, published and modified dates

Because the post ID is the reference, a full sync is always safe to run again. It updates what is already there.

#Large sites

A full sync walks your posts in batches of 50 and paces itself against the API's rate limits, so a big library takes a while but never floods anything. Two things worth knowing:

  • Pushing is not indexing. When the push finishes, Datalumo still has to read and embed everything it received. Progress continues on the source page in your dashboard after WordPress reports it is done.
  • Use a real cron on big sites. Background work in WordPress is normally triggered by visitors. On a site with tens of thousands of posts, a server cron running wp cron event run --due-now keeps the run moving steadily.

If a sync stops early, the reason is shown next to the button. Rate limits and temporary server errors are retried automatically; a rejected post or an invalid key stops the run so you can fix it.

#Add the chatbot

  1. Create a chat widget in Datalumo.
  2. Add this site's domain to the widget's websites list. That is what authorises the widget in the browser.
  3. Copy the widget key from the widget editor, under For developers. It is safe to have in a page.
  4. Paste it on the Chatbot tab and tick Show the floating chat on every page.

To place the chat inside a page instead of floating it, use a shortcode:

[datalumo_chat]

Create a search widget, add your domain to its websites list, and paste its key on the Search box tab. Then drop the box wherever you want it:

[datalumo_search]

Both shortcodes accept a widget attribute if one page needs a different widget than the site default:

[datalumo_search widget="ORG_ID/WIDGET_ID"]

In the block editor, add a Shortcode block and paste the same thing.

Enhanced search replaces the ranking behind your existing search page. A visitor searches as usual, your theme renders the results as usual, but the order comes from Datalumo instead of from WordPress' keyword matching.

On the Enhanced search tab:

Setting Notes
Enable Off by default. If Datalumo is unreachable, WordPress' own search takes over silently.
Widget key A search widget key. This site's domain must be on its websites list.
Limit to post types Leave everything unticked to improve every search.
AI summary A short streamed answer above the results, written from the top matches.
Summary placement Optional CSS selector of your results container, and before or after the list. Detected automatically when empty.

Nothing in your theme has to change. Your templates, excerpts, and pagination keep working, and search filters your visitors apply (a post type, a WooCommerce price range) still narrow the results.

A few details worth knowing:

  • The top 50 matches are fetched once per search and paged through locally, so pagination stays fast.
  • The AI summary only appears for questions, not single keywords, and only when there are results.
  • Result clicks are reported back to Datalumo automatically, tied to the search that produced them, so search analytics in your dashboard covers your theme's own result list.

#WooCommerce

When WooCommerce is active, product searches keep their usual behaviour: catalog sorting (price, popularity, rating, newest) is honoured, products hidden from search stay hidden, and the price filter widget applies to the results.

#Visitor identity

Turn on Visitor identity on the Chatbot tab and paste the widget's identity signing secret (also under For developers). Logged-in users then keep their conversation history between visits.

The plugin signs each WordPress user id on the server with that secret, so a visitor cannot claim to be someone else. The secret itself stays in your database and never reaches the browser. See signed visitor identity for the mechanics.

#For developers

The plugin ships a set of filters for the cases the settings screen does not cover.

Filter Use it to
datalumo_page_payload Add or change fields on the page pushed for a post
datalumo_is_indexable Skip individual posts
datalumo_render_shortcodes Render shortcodes into synced content instead of stripping them
datalumo_bulk_sync_batch_size Push smaller batches during a full sync (50 max)
datalumo_search_max_results Change how many ranked results a search fetches (50 max)
datalumo_should_intercept_search Decide per query whether Datalumo ranks it
datalumo_resolve_args Adjust the query used to load matched posts
datalumo_sort_map Map your own orderby values to a sort
datalumo_summary_filters Narrow the AI summary the same way your results are narrowed
datalumo_results_selector Point click tracking at your results container

For example, to index a custom field alongside the post content:

add_filter('datalumo_page_payload', function (array $payload, WP_Post $post): array {
    $payload['meta']['sku'] = get_post_meta($post->ID, '_sku', true);

    return $payload;
}, 10, 2);

Custom field and taxonomy mappings can also be defined per sync with the same filter, which is the recommended route until the settings screen covers them.

#Troubleshooting

Symptom Check
Connect & test fails Organisation ID and API key belong to the same organisation; the key has pages.write
Nothing appears in the source The post type is ticked for that sync, and the post is published
Content synced but not searchable yet Indexing runs after the push; watch progress on the source page
Full sync stalls Set up a server cron for WordPress' scheduled tasks
Chat or search box does not appear The site's domain is on the widget's websites list, and the widget key is ORG_ID/WIDGET_ID
Enhanced search looks unchanged The toggle is on, a search widget key is set, and the searched post type is within the limit you set
Conversations do not carry over Visitor identity is on and the signing secret matches the widget
  • Introduction for the other ways to integrate
  • Widget SDK for embedding search and chat by hand
  • Authentication for API keys, permissions, and widget access
  • Pages for the endpoints the plugin uses under the hood