User manual — Smart QR and totems (Xabia Agent Core)

Product version: Xabia Agent Core v1.0.59 (May 2026)
Included in the Core license — no separate paid plugin or add-on required.
Online PDF: https://xabia.ai/docs/manual-usuario-xabia-smart-qr.pdf
Online HTML: https://xabia.ai/docs/manual-usuario-xabia-smart-qr.html
Core Manual (general context): xabia-core-user-manual.md

Quick guide (5 minutes)

1. Install and activate Xabia Agent Core ( xabia-agent-core ) with a valid license.
2. Create an agent, synchronize data with at least one column marked as IDENTITY (ENTITY) (§4).
3. Publish a landing page with the agent shortcode, for example:
   
4. In Edit Agent → Smart QR / Totems tab , select that page as Landing Page and save.
5. On the same tab, click Generate QR next to the entity you want (room, product, space…).
6. Download the PNG, print it, or share it. When scanned, the visitor arrives at the chat linked to that entity (tunnel effect).
7. For a tablet in reception , use the path /xabia-box/?x_project=ID_AGENTE or activate Totem Mode (§8).

Important: If you update the Core or use /xabia-box/ , visit Settings → Permalinks → Save Once to regenerate the URL rules.

1. What is Smart QR in Xabia?

Smart QR is the Core layer that connects the physical world (posters, labels, totems, brochures) with the Xabia chat. When someone scans a code or opens a tunnel link:

• The assistant knows from what point they have arrived (museum room, hotel room, specific product…).
• RAG knowledge can be filtered by entity ( ente_id ).
• The greeting and tone are customized for that location.
• Conversations can be tagged in analytics as Smart QR source / tunnel (if you have the Core analytics tab enabled).

All of this is included in Xabia Agent Core since version 1.0.59. The old separate plugin “Xabia Smart QR” is obsolete ; if you still have it installed, deactivate and remove it.

1.1 Typical use cases

1.2 What Smart QR is not

• It does not replace data synchronization: it must have indexed knowledge (CSV, SQL, CPT…) with identified entities.
• It is not a generic QR generator for arbitrary URLs: it is intended for tunnels to your Xabia agent with entity context.
• No separate Polar addon license is required: it is part of the Core .

2.

Key concepts

2.1 Entity ( ente_id )

An entity is the logical unit of knowledge segmentation: a room, a product, a company, a bedroom…

• In the agent column mapping , mark IDENTITY (ENTITY) in the field that stably identifies each row (slug, code, internal ID).
• After synchronizing data , each row is associated with an ente_id (for example, sala-impresionismo , okana , producto-442 ).
• The global special value means “without a specific entity”; it is not suitable for generating tunnel QR codes.

2.2 Tunnel effect

When the visitor arrives with an active entity (via URL ?ente_id= or POI scan ?xqr= ), the Core injects an internal context of the following type into the model’s prompt:

The user has arrived via a Smart QR tunnel link to the “Impressionism Room” section. Greet them specifically…

The visitor does not see that text; he only notices a greeting and more precise answers.

2.3 Landing Page

It’s a published WordPress page that contains the agent’s shortcode. The generated QR codes point to:

 If you do not configure a landing page, the system may use the generic route. https://su-dominio.com/pagina-del-chat/?ente_id=sala-impresionismo

/xabia-box/?x_project=ID_AGENTE&ente_id=… .

2.4 Point of Interest (POI) and URLs ?xqr=

In addition to tunneling per entity, the Core supports POI identifiers in the URL:

 (or the alias) https://su-dominio.com/?xqr=sala-3&x_project=mi-museo

?xid= ). This activates a scanning session, automatic greeting, and, if the POI has ente_slug , anchors the chat to that entity.

The POI data can come from:

• Internal registry ( xabia_qr_poi_registry ),
• xabia_qr_poi table,
• Or rows of the agent’s RAG knowledge.

2.5 Route /xabia-box/

Full-screen experience designed for totems: no floating button, chat taking up the screen.

 3. Where is it located in the WordPress dashboard? https://su-dominio.com/xabia-box/?x_project=mi-museo&ente_id=recepcion

It does not appear in Xabia Agent → Addons as a paid product: it is Core functionality.

4. Prepare data with entities

4.1 Example CSV (museum)

file salas.csv :

 codigo_sala;nombre_sala;texto_guia;piso sala-impresionismo;Impresionismo;Obras de Monet, Renoir y Degas entre 1860 y 1880.;1 sala-barroco;Barroco;Escultura y pintura europea del siglo XVII.;2 In the agent: codigo_sala;nombre_sala;texto_guia;piso sala-impresionismo;Impresionismo;Obras de Monet, Renoir y Degas entre 1860 y 1880.;1 sala-barroco;Barroco;Escultura y pintura europea del siglo XVII.;2

1. Upload the CSV and Connect/Map .
2. Mark codigo_sala as IDENTITY (ENTITY) .
3. Label nombre_sala as title and texto_guia as main text.
4. Synchronize data → Train (if using vector search).

After synchronizing, in Smart QR / Totems you will see entities sala-impresionismo and sala-barroco .

4.2 SQL / WordPress with entity

If you are using the WordPress Content Assistant , mark the field that identifies each record (post ID, slug, SKU, etc.) as Entity . The resulting slug will be the ente_id in the agent’s memory.

5.

Configure the “Smart QR / Totems” tab

Open Xabia Agent → Edit agent → Smart QR / Totems .

5.1 Landing Page

1. Create a page in WordPress, for example “Museum Assistant” .

2. Insert the shortcode:

    Publish 

3. the page.

4. In the Landing Page dropdown, select it and press Save Agent .

5.2 Totem mode (kiosk)

You can also force minutes in the shortcode:

 The value of the shortcode 

prevails over the agent’s defect.

5.3 Entity and Generator Table

With the agent saved and entities in memory, the tab displays:

Clicking Generate QR opens a modal window with:

• Code preview

• Download PNG / Download SVG

• Copy link , Copy shortcode , Copy image

• Suggested shortcode:

   6. Link Types (Reference) 

6.1 Tunnel per entity (recommended for printed QR code)

 Automatically generated by the panel. It's the one that encodes the PNG from the generator. https://ejemplo.com/asistente-museo/?ente_id=sala-impresionismo

6.2 Embedded shortcode with fixed entity

Useful on a landing page dedicated to a single room (without depending on ?ente_id= in the URL):

 6.3 Physical POI ( 

?xqr= )

 The visitor receives a contextual greeting from the POI. Configure the POI in a record/table or let the Core infer data from the RAG knowledge. https://ejemplo.com/?xqr=placa-entrada&x_project=mi-museo

6.4 Full Screen Totem

 With preselected entity: https://ejemplo.com/xabia-box/?x_project=mi-museo

 In the totem's browser, open that URL in https://ejemplo.com/xabia-box/?x_project=mi-museo&ente_id=recepcion

kiosk mode (full screen OS).

7.

Complete examples by sector

7.1 Museum with a landing page and QR codes per room

Objective: Poster in each room with a different QR code.

1. mi-museo agent, CSV of rooms (§4.1).
2. Page /asistente/ with .
3. Landing page configured in Smart QR / Totems.
4. Generate QR code for sala-impresionismo → print PNG.
5. The visitor scans → open chat → contextual greeting → text-based responses in that room.

Test without printing: open the tunnel URL on your mobile device or use the Playground with the same ente_id .

7.2 Rural Hotel (Astei-style)

Objective: QR code in each house with information and a link to booking.

1. Synchronize accommodations with entity = house slug ( okana , etxola , …).
2. Landing with the main agent.
3. QR code per entity; the tunnel focuses the context on that house.
4. If you have Xabia Avirato , availability questions can be combined with the entity context (see Avirato manual).

7.3 Store with QR code on shelf

1. CSV of products with SKU column as ENTITY .
2. QR points to ?ente_id=sku-12345 .
3. Personality Instructions: “If the visitor arrives via a product QR code, prioritize the data sheet, stock, and price of that SKU in the context.”

7.4 Municipal reception (totem)

1. atencion-ciudadana agent.
2. Activate Totem Mode with 8 minutes of inactivity.
3. Tablet with /xabia-box/?x_project=atencion-ciudadana .
4. No printed QR code: fixed counter experience.

8. Chat behavior (visitor)

1. Opening: initial greeting of the agent or POI greeting if he/she came by ?xqr= .
2. RAG context: the Brain prioritizes fragments of the active ente_id (strict mode).
3. First person: in tunnel/QR mode, the model usually responds as a guide to the place (“In this room you will find…”).
4. Language: responds in the language of the visitor’s last message (Core polyglot); the QR code does not specify the language.
5. Totem: after inactivity, it returns to the initial state (useful in shared screens).

9. Traffic analytics and origin

If you use the Core Analytics tab, conversations can be categorized:

• Web — normal chat on the web.
• Smart QR / tunnel — arrival with active QR code.

It serves to measure how much use physical signs generate compared to the web widget.

10. Problem Solving

11.

Modular architecture (light technical reference)

Smart QR is distributed in modules within the Core ZIP file :

Do not install any additional add-ons for Smart QR. The Avirato , MEC , and Woo add-ons are standalone and optional.

12. Migration from the “Xabia Smart QR” plugin

If in older installations you had the xabia-smart-qr plugin separately:

1. Update Xabia Agent Core to v1.0.59 or higher.
2. Deactivate and remove xabia-smart-qr in Plugins .
3. Check Smart QR / Totems at your agent: the functionality is already there.
4. I regenerated permalinks if you use /xabia-box/ .

No need to migrate addon license: Smart QR no longer has its own Polar product.