5NFiveNeuralsGuide

For developers

Connect a shop to NEURA

NEURA's assistants answer shoppers from the shop's own data. You do two things: build a small bridge so NEURA can read the shop, and add one line to the shop's pages for the chat box. Any shop can connect, including one you built yourself.

NEURA only readsIt never changes anything in the shop: no orders, no prices, no stock. Every address you build is a GET.
  1. 1Build the bridgeYou
  2. 2Say what your shop can doYou
  3. 3Check your workYou and the shop owner
  4. 4Connect your shopThe shop owner
  5. 5Add the chat boxYou and FiveNeurals

Before you start

Download the OpenAPI fileIt describes every address and every field. Keep it open while you build, or point a code generator at it.Download the OpenAPI file
Using an AI coding tool?Add this address to it as an MCP server. Your tool can then ask NEURA what each address must answer, see a working sample for each, and read the rules bridges get wrong. It never sees your shop and needs no token.
https://api.fiveneurals.com/v1/developers/mcp

1 · Build the bridge

First ask FiveNeurals whether a ready-made bridge exists for the shop's system. If it does, install it like any other add-on and go to step 2. If not, build the addresses below. Put them under any prefix, usually /neura/v1.

1. Start with these threeEnough to connect. The assistant can find products and talk about them.
AddressGives the assistant
GET /healthWhat your shop can do (step 2)
GET /productsA page of products, and search
GET /products/{id}One product
2. Add these for better answersEach one you add, the assistant can do one more thing.
AddressGives the assistant
GET /inventoryStock: whether something can be bought now
GET /policiesReturns, shipping and warranty pages
GET /categoriesYour categories: what you do sell when nothing fits
3. Only for order questionsFor a shop that wants the assistant to look up orders.
AddressGives the assistant
GET /ordersA page of orders, and search by email or order number
GET /orders/{id}One order
GET /customers/{id}One customer, never a member of staff
Not sure what the shop needs?Build the first three, connect, and add the rest later. Nothing breaks: what the assistant can't answer, it hands to the shop's team.
  • Everything is GET. No address changes anything in the shop.
  • Check the shop token on every address except /health. NEURA sends Authorization: Bearer <shop token>; refuse a request without it. Read the token from a setting, for example NEURA_SHOP_TOKEN, never from code. The shop owner makes the real token in their NEURA dashboard and sends it to you; until then, put any text in that setting to test.
  • Pages by cursor, not page number. Return an opaque next_cursor; NEURA sends it back unchanged.
  • The exact format of every answer is in the OpenAPI file you downloaded.
A sample answer: GET /products/1042
{
  "external_id": "1042",
  "title": "Wool Hiking Socks",
  "description": "Warm merino socks for long walks.",
  "status": "active",
  "url": "https://yourshop.example/products/wool-hiking-socks",
  "image_urls": ["https://yourshop.example/images/wool-hiking-socks.jpg"],
  "category_ids": ["12"],
  "variants": [
    {
      "external_id": "1042-m",
      "title": "M",
      "options": { "size": "M" },
      "price": { "amount": "12.00", "currency": "EUR" },
      "in_stock": true,
      "stock_quantity": 8
    },
    {
      "external_id": "1042-l",
      "title": "L",
      "options": { "size": "L" },
      "price": { "amount": "12.00", "currency": "EUR" },
      "in_stock": false,
      "stock_quantity": 0
    }
  ]
}
  • Each size or colour is a variant, with its own price and stock. A product with neither still needs one variant: that is where its price and stock go.
  • "in_stock" is true only if it can be bought now. Here size M can, size L can't.
  • A price is text and a three-letter currency: "12.00" and "EUR".
  • The list, GET /products, sends the same product, many at a time, in "items".

2 · Say what your shop can do

/health tells NEURA what your bridge can do. The assistant gets only what is on this list, so it is the one answer to get exactly right.

Example: a bridge with groups 1 and 2 from step 1
{
  "status": "ok",
  "spec_version": "1.0",
  "platform": "yourshop",
  "capabilities": [
    "product.read",
    "product.search",
    "inventory.read",
    "policy.read",
    "category.read"
  ]
}
FieldWhat to write
statusExactly "ok".Anything else, even "healthy", and NEURA treats your shop as down.
spec_version"1.0", the version of this format.The check tool fails without it.
platformYour shop system's name, in any words. For information only.
capabilitiesWhat your bridge can do: the table below.
What to listFind each address you built in step 1, and write its word in the list.
You builtWrite this word
1. Start with these three
GET /healthnothingThis address is the list itself.
GET /products
GET /products/{id}
product.read
Search: GET /products?q=…product.search
2. Add these for better answers
GET /inventory?variant_ids=…inventory.read
GET /policiespolicy.read
GET /categoriescategory.read
3. Only for order questions
GET /orders/{id}order.read
Search: GET /orders?email=…Also by phone, customer_id and order_number.order.search
GET /customers/{id}customer.read
Extras
GET /products?updated_since=…Returns only what changed since then.sync.incrementalOptional. Without it, NEURA reads every product each time.
Change messagesYour shop tells NEURA when something changes.nothing yetNEURA can't receive them yet. Leave out events.realtime.
Leave one out: that's safeThe assistant isn't given that job, so it never tries it. Build it later, add it to the list, and NEURA sees the change within a minute. Nothing to reconnect.
List one you didn't build: it fails quietlyNEURA reads a missing address as nothing there. List product.search while your search still finds nothing, and the assistant tells shoppers you don't sell things you do. The check tool in step 3 can't tell either.

No token on this one. /health is the only address anyone may open, so you can check your bridge from a browser. Put no shop data in it.

3 · Check your work

The shop owner runs the check from their NEURA dashboard, as often as you need. There is no tool to download. It asks your bridge about 20 questions, the way the assistant will, and names anything wrong. Every question is a GET, so nothing in the shop changes.

  1. 1
    The shop owner sends you the shop tokenShop owner
    They make it in their NEURA dashboard. Put it in your bridge's setting, in place of your test text.
  2. 2
    Put your bridge onlineYou
    At an https:// address on the public internet. NEURA won't call localhost, a private network or plain http://.
  3. 3
    Send the shop owner the bridge's addressYou
    The exact address on your live shop, for example https://yourshop.example/neura/v1. NEURA doesn't follow redirects. The address that passes is the one that gets connected, and it can't be changed afterwards.
  4. 4
    The shop owner presses CheckShop owner
    If something is wrong, they send you the full check. Fix what it names, then ask them to check again.
Example: the full check the shop owner sends you (shortened)
NEURA check · https://yourshop.example/neura/v1 · 2026-10-01 09:30 UTC

✘ auth.rejects_wrong_token     /orders accepted an invalid bearer token (HTTP 200)
    → The token is being ignored rather than verified.
⚠ products.search_no_match     search returned results for nonsense text
    → Over-broad matching floods the agent's context with irrelevant products.
✔ health                       ok
✔ products.get_missing         ok
…
18 passed · 1 failed · 1 warning(s)
  • ✘A problem. The shop owner can't connect while there is one.
  • ⚠A warning. It doesn't stop the owner connecting, but each one means a worse answer for a shopper. Fix it anyway.
The check proves the format, not the factsA clean check means your answers have the right shape, not that they are true. Compare a few products in the shop with what your bridge sends:
  • Stock. A sold-out product says "in_stock": false.
  • Prices. The same as on the shop's page, with the currency as three capital letters, such as EUR.
  • Hidden products. One the shop doesn't show yet comes as "status": "draft". The assistant never mentions a draft.
  • Customers. If you built /customers/{id}, a member of staff's id answers 404.

4 · Connect your shop

You have nothing to press here. The shop owner connects the shop in their dashboard, and NEURA reads it for the first time.

  1. 1
    The shop owner presses ConnectShop owner
    In their dashboard: Connect and copy my catalogue. It works only after a check with no problems.
  2. 2
    NEURA copies the shop's catalogueNEURA
    Your products, page by page, and your categories and policy pages if you built them. Orders and customers are not copied.
  3. 3
    The owner sees Your shop is connectedShop owner
    Then Your catalogue is copied, with the number of products.
Your part after connecting
  • Keep the bridge online, at the same address. The assistant asks it questions live while shoppers chat: searches, products, stock.
  • Keep the shop token secret. Never in a web page, the browser or a public code repository. NEURA can't show it again, not even to the shop owner: if it's lost, the owner makes a new one.
  • A new token from the owner? Put it in straight away. Until you do, the assistant can't read the shop, and the old token still works for whoever has it. Then ask the owner to press Check again.

5 · Add the chat box

One line of HTML puts the chat box on the shop's pages.

  1. 1
    Send FiveNeurals the shop's web addressesYou
    Every exact address the chat box will run on, for example https://yourshop.example and https://www.yourshop.example, and a test site if you have one. One key can cover them all.
  2. 2
    FiveNeurals makes the chat box keyFiveNeurals
    A public key that starts with fn_pk_. It works only from the addresses you sent. A key from a NEURA test system starts with fn_pk_test_. It works the same way, and “test” has nothing to do with practice mode.
  3. 3
    Add the line to every page shoppers seeYou
    Not your admin pages: staff questions would use AI and mix with real shoppers' chats.
<script src="https://api.fiveneurals.com/v1/widget/widget.js" async
        data-neura-key="fn_pk_…"></script>
  • The key is public, and that's fine. It works only from the addresses it was made for. www. and no www., http and https, are different addresses.
  • Never put a secret key in a page. Secret keys start with fn_sk_, and anyone can read a page's source. NEURA refuses one there, and the chat box says why.
  • Keep the key in the shop's settings, like the shop token, not in the template. A new key then needs no code change.
  • It won't break your page. One file, no dependencies, loaded async. It draws itself in its own box, so your styles don't reach it.
  • Strict content security policy? Allow our address in script-src, and in connect-src with both https:// and wss://. No unsafe-inline needed.
How you'll know it works
  • Open a shop page: the chat button appears at the bottom right.
  • Send one test message (it uses AI). The shop owner's dashboard then shows The chat box is on your shop.
  • In practice mode, every reply is a short your message has been received note. The owner reads the real reply in Review.
  • Every message gets We could not reach the assistant? The page's address is probably not on the key: check www., http or https, and the test site.
SettingsEach one is an attribute on the same line.
data-neura-key
The chat box key. Required
data-neura-title
The panel's heading. Default Chat with us
data-neura-open
true opens the panel when the page loads
data-neura-agent
Usually leave it out: NEURA picks the right assistant for each question. care (questions about the shop) or sell (help choosing) sends every question on the page to that one
data-neura-api
Only if you serve widget.js from somewhere else: NEURA's address. By default, the address the file came from
data-neura-products
The products a page shows, for suggestions. See below
data-neura-pairs-auto-open
true lets a suggestion open the panel. See below
data-neura-customer-pass
A signed-in customer's pass, for order questions. See Optional: order questions
data-neura-sign-in-url
Your sign-in page, for order questions. See Optional: order questions
Optional: suggestions on the basket pageTell the chat box which products a page shows, and it suggests what goes with them, in the chat panel.
<script src="https://api.fiveneurals.com/v1/widget/widget.js" async
        data-neura-key="fn_pk_…"
        data-neura-products="1042,1077"></script>
  • The ids your bridge sends (each product's external_id), separated by commas. At most 10 count.
  • Only on the page that shows them, usually the basket. The line normally lives in a shared layout: let that page hand the layout its ids, and leave the setting out everywhere else.
  • This uses AI. The first time a product appears here, NEURA asks an AI model once, in the background, what goes with it, and keeps the answer. The shopper never waits.
  • Want the panel to open by itself? Add data-neura-pairs-auto-open="true". It opens at most once per visit, and only when there is a suggestion. Off by default.
  • Nothing shows? Failures here are silent on purpose: the shopper is about to pay. Look at the suggestions request in your browser's Network tab, and ask the shop owner whether their shop has suggestions.

Optional: order questions (part of NEURA-CARE)

NEURA-CARE can answer “Where is my order?” in the chat box for a shopper who is signed in to the shop, and only about their own orders. Your shop's server tells the chat box who is signed in, with a short-lived pass that only your server can make.

It needs the order addresses from step 1 (group 3), listed in /health. With order.read, the assistant answers about an order by its number. Add order.search and customer.read, and it also finds a shopper's orders when they don't give one.

  1. 1
    The shop owner makes the secretShop owner
    On Shop connection in their NEURA dashboard: Make the secret. NEURA shows it once, and they send it to you. It starts with fn_cs_.
  2. 2
    Keep it on your shop's serverYou
    In a setting, for example NEURA_CUSTOMER_SECRET, like the shop token. Never in a web page: anyone who has it can make a pass for any customer. NEURA refuses it in a page. A new secret from the owner stops the old one at once, so put it in straight away.
  3. 3
    Make a pass on every page a signed-in customer opensYou
    Your server makes a fresh one each time it draws the page, and writes it into the chat box line. Nobody presses anything.
Make the passA pass is a JSON Web Token (JWT), signed with HS256. Sign it with the whole secret, fn_cs_ included, exactly as the shop owner sent it. Any JWT library makes one in a few lines:
PHP, with firebase/php-jwt
use Firebase\JWT\JWT; // composer require firebase/php-jwt

// $customerId: from your shop's own sign-in session, never from the request.
$now = time();
$pass = JWT::encode([
    'sub' => (string) $customerId, // text, exactly as your bridge sends it
    'iat' => $now,
    'exp' => $now + 15 * 60,       // at most 15 minutes
], getenv('NEURA_CUSTOMER_SECRET'), 'HS256');
Node.js, with jsonwebtoken
const jwt = require("jsonwebtoken"); // npm install jsonwebtoken

// customerId: from your shop's own sign-in session, never from the request.
const pass = jwt.sign(
  { sub: String(customerId) }, // text, exactly as your bridge sends it
  process.env.NEURA_CUSTOMER_SECRET,
  { algorithm: "HS256", expiresIn: "15m" }, // adds iat and exp: at most 15 minutes
);
sub
The signed-in customer's id, as text: the same id your bridge sends as customer_external_id on their orders, because NEURA keeps only the orders whose id matches. Write it in quotes, "385", not 385: NEURA refuses a number. Up to 128 characters
iat
When you made the pass, in seconds since 1 January 1970 (Unix time). A pass made more than a minute ahead of NEURA's clock is refused, so keep your server's clock right
exp
When the pass stops working: at most 15 minutes after iat. A shopper who keeps a page open longer is asked to reload it, which makes a new pass

These three and nothing else: NEURA refuses a pass with any other field, so a name or an email is never sent by mistake. It also refuses a pass signed any way but HS256.

Put it in the chat box lineTwo more settings on the line from step 5.
<script src="https://api.fiveneurals.com/v1/widget/widget.js" async
        data-neura-key="fn_pk_…"
        data-neura-customer-pass="eyJhbGciOiJIUzI1NiIs…"
        data-neura-sign-in-url="https://yourshop.example/login"></script>
data-neura-customer-pass
The pass, only when the shopper is signed in. For everyone else, leave the setting out: no pass means not signed in
data-neura-sign-in-url
Optional. Your shop's sign-in page, as a full address with https://. A shopper who isn't signed in and asks about an order gets a Sign in link to it. A short address such as /login shows no link
Keep each customer's orders private
  • Only from your shop's own sign-in session. Take the customer's id from the session your shop already uses to know who is signed in. Never from anything in the request, such as ?customer=385, and never build an address that makes a pass for whoever asks: anyone could then read another customer's orders.
  • Never cache a page that carries a pass. Send it with Cache-Control: private, no-store, and keep it out of your shop's own page cache. A cached copy would give one customer's pass to everyone who opens the page, for up to 15 minutes, or keep showing the same customer a pass that has stopped working.
What the shopper sees
Signed in
Answers about their own orders: status, items and tracking. Another customer's order number gets the same answer as a number that doesn't exist.
Not signed in
“Please sign in to your account so I can help with your orders. Or contact our store:” and the shop's contact details from the dashboard. With data-neura-sign-in-url, a Sign in link under it. The same words whatever order number they type, so nobody can find out which orders exist.
Signed in, page open longer than its pass
“Your sign-in on this page has timed out. Please reload the page and ask again.”
How you'll know it works
  • On a shop that is live, sign in as a test customer with an order, open a page and ask Where is my order? The assistant answers about that customer's orders. In practice mode the shopper sees only the received note (step 5).
  • Each answer says what NEURA made of the pass, in customer_pass: valid, expired or invalid, and null when the page sent none. Why, in customer_pass_reason. Find it in your browser's Network tab: the chat's live connection (stream, under Messages), or the chat request when there is no live connection.
  • invalid? The browser's console says why, once per page, after the first message: NEURA: the customer pass in data-neura-customer-pass was refused, so this shopper is treated as not signed in: and the reason.
  • Sign out and ask again: you are asked to sign in.

Optional: product views (part of NEURA-SELL)

NEURA-SELL can show the shop owner a Sold out list: sold-out products that shoppers kept opening in the last 7 days. See what the owner sees

For it, your shop's server tells NEURA each time a shopper opens a product or adds one to the basket. Build it only if the shop owner wants it.

  1. 1
    The shop owner decides, and signs a data agreementShop owner
    With FiveNeurals. Without it, NEURA stores nothing about shoppers.
  2. 2
    FiveNeurals makes your secret keyFiveNeurals
    It starts with fn_sk_ and is made for sending product views. It can only be made once the agreement is recorded.
  3. 3
    Build a setting, off by default, and the sendingYou
    While the setting is off, your server sends nothing. NEURA has no switch of its own: what it receives, it keeps.
  4. 4
    The shop owner turns the setting onShop owner
    Once the shop asks its shoppers for permission. The agreement makes that the shop's job, so ask the shop owner how it is done.
One request per event
POST https://api.fiveneurals.com/v1/observe/events
Authorization: Bearer fn_sk_…
Content-Type: application/json

{
  "event_id": "ev_7f3a9c2e1b4d4e8a",
  "session_id": "s_2c9e41b7d05f4a63",
  "type": "product.viewed",
  "product_id": "1042",
  "occurred_at": "2026-10-01T09:30:00Z",
  "in_stock": false
}
event_id
Your own id for this event: 16 to 64 characters, using only a to z, A to Z, 0 to 9, hyphens (-) and underscores (_). Send the same one again and it counts once, so a retry is safe
session_id
One per shopper visit, so the list counts visits and not only views: 16 to 128 characters, the same kinds as event_id. Never the shop's session cookie itself: make it from the session with a secret only your server holds (a keyed hash)
type
product.viewed when a shopper opens a product page. cart.added when a product goes into the basket, once the add worked
product_id
The product's external_id, exactly as your bridge sends it, up to 128 characters. Dots, slashes and spaces are fine
occurred_at
When it happened, with a time zone. Not older than 7 days, and not more than 5 minutes ahead
in_stock
Views only: could the product be bought at that moment (at least one variant in stock), true or false. Leave it out of cart.added

Send these six fields and nothing else. NEURA refuses a request with any other field, so nothing more about a shopper can be sent by mistake.

  • From your server only. Never from the shop's pages: anyone can read a page, and NEURA refuses a secret key sent from one.
  • Nothing about who the shopper is. No name, email, IP address or browser details.
  • Never slow a page down. Send in the background, for example from a queue.
  • Nothing for search-engine robots. Check the browser details on your server against a list of known robots, and send nothing for one, or for a request with none. A robot keeps no cookie, so each page it reads would count as a new visitor who never adds to the cart. The browser details themselves are still never sent.
  • Kept for 7 days, then deleted. If the agreement ends, everything is deleted at once.
How you'll know it works
  • Each event is answered 202 with "stored": true. The same event_id again is answered "stored": false: it was already counted.
  • A wrong or extra field is answered 400, and the error names the field.
  • 403 with DPA_REQUIRED: the agreement isn't recorded yet. Ask the shop owner.

Webhooks to NEURA

Messages your shop's server sends to tell NEURA that a product or order changed. Step 2 calls them change messages.

Don't build these yetNEURA has no address that receives them. The OpenAPI file already describes them (entityChanged, under webhooks): skip that part for now, and leave events.realtime out of your list (step 2).

You lose nothing. The chat box asks your bridge live, so it sees a new product or a stock change straight away. Only NEURA's own copy of the catalogue, used by the shop owner's dashboard, waits until the owner presses Sync now.

If something doesn't work

In the full check the shop owner sends you
The bridge refused the shop token
The token in your bridge's settings isn't the one the shop owner made. Put theirs in exactly, then ask them to press Check again.
Could not reach the address
Your bridge isn't online at that address, or the address isn't public. NEURA calls only public https:// addresses (step 3).
There is no bridge at this address
The address isn't your bridge's (send the one /health sits under), or it redirects. NEURA doesn't follow redirects (step 3).
Its "status" is not "ok"
/health must answer "status": "ok", exactly (step 2).
/health passes, everything else fails
Usually your bridge's database settings. A /health that doesn't touch the database stays green while every other address fails.
In the chat box
The chat button doesn't appear
The line isn't on this page (look in the page's source), a strict content security policy blocks it (step 5), or the shop still serves an old cached page.
Every message gets We could not reach the assistant
The page's address isn't on the chat box key: check www., http or https, and the test site (step 5).
A secret key may not be used from a web page
The line holds a secret key (fn_sk_). Put the chat box key (fn_pk_) there, and keep secret keys on your server.
In the assistant's answers
It says the shop doesn't sell something it does
An item listed in /health whose address isn't built: NEURA reads its 404 as “nothing there” (step 2). Or your search misses the words shoppers use: try them on /products?q= yourself.
A sold-out product is called in stock, or a price shows the wrong currency
Compare your bridge's answers with the shop by hand (step 3): in_stock, and a three-letter currency code.
Order questions
The console says the signature does not match
Your setting doesn't hold the shop's current secret. Use the whole secret, fn_cs_ included, exactly as the owner sent it. A new secret from the owner replaces the old one at once.
The console says this shop has no customer sign-in secret yet
Ask the shop owner to press Make the secret on Shop connection.
The console says sub must be text
The customer's id went in as a number. Turn it into text: (string) $customerId in PHP, String(customerId) in Node.js.
Signed in, but asked to sign in
customer_pass is null: the page has no pass. Look for data-neura-customer-pass in the page's source. Missing on a page you know you added it to? A cache served an old copy.
Signed in, but the assistant finds no orders
sub isn't the id your bridge sends as customer_external_id on that customer's orders. Compare the two for your test customer.
Product views
The Sold out list stays empty
It lists only products opened while they were sold out, so check one was. Then read NEURA's answer to your request: 403 DPA_REQUIRED means no agreement yet, and a 400 names the wrong field. No request at all? The setting is off.
The full specificationEvery field of every address. Where this page and the specification disagree, the specification is right.
Download the OpenAPI file