Live data sources (menu, price list, stock)

A data source is a URL you own (a menu, a price list, stock, open slots) that the platform fetches on a schedule, turns into plain text and places in front of the agent when a call starts. There is no lookup during the call: the agent answers "which is the cheapest crêpe?" from the whole list, from the first word.

When to use it#

• The knowledge base is for documents that change rarely and are searched. A catalogue that changes daily and has to be read as a whole (prices, what comes with what) fits a data source better.
• A tool fetches one answer while the caller waits. Use a tool for per-customer lookups (an order, a booking) and a data source for the list everyone asks about.

Connect a source#

1. Open the agent and go to its Data sources tab.
2. Click Add data source and answer Where does the data come from? by picking your provider. iotSoft POS is first in the list; if your provider is not there, use Catalogue JSON API or Text or CSV page. For a knowledge base document, see Internal guidance below.
3. Enter the URL and, if your provider needs one, the Access token. The token is stored as a secret on the project and is never shown again.
4. Set Refresh every (minutes) (minimum 5, default 60) and, if needed, Max characters (default 15000).
5. Click Connect and fetch. The first fetch runs immediately, so you see at once whether the address and the token work.
6. Attach the source to the agent, then Save and Deploy.

Preview what the agent sees shows the exact text the agent gets.

How it stays fresh#

Every source is fetched in the background on its own schedule, by exactly one server at a time; a call never waits for a fetch. A fetch that finds nothing new leaves the stored data untouched and only notes when the source was last checked, so the list shows both checked and changed times. A failed fetch keeps the last good snapshot in use and marks the source error with the reason; nothing changes mid-call. Refresh now fetches outside the schedule.

Internal guidance from the knowledge base#

A source can also be a knowledge base document, for example the agent's sales playbook. You write and improve it in the knowledge base, with drafts and publishing, and the agent follows it on every call.

1. In the Knowledge base, write or upload the document in a collection the agent does not search, and publish it.
2. On the agent's Data sources tab, click Add data source and pick Knowledge base document.
3. Choose the Collection and the Document. Leave Role on Internal guidance.
4. Click Connect and fetch, then Save and Deploy.

What the Internal guidance role means:

• The agent follows the text as part of its instructions. It does not read it out, summarise it or confirm that it exists, whoever asks.
• An agent cannot search the collection its guidance comes from. If you also attach that collection to its knowledge, saving is refused, because a caller could find the text with a question.
• The agent always gets the published version. While you edit the document it keeps the last published one. As soon as you publish, the next call has the new version.
• If you archive or delete the document, the agent stops using it at once.
• The list shows which version is in use, and every call records the version it ran on.
• A document longer than Max characters is not cut: the source shows an error until you shorten it or raise the limit.

No text a model sees is perfectly secret. Do not put in the guidance anything that must never get out, such as pay rates, passwords or customer details.

Describing your own JSON#

With Catalogue JSON API, the Mapping (JSON) tells the platform where things live in your feed, in dot notation: the list of categories (list_path), the category name, the items, each item's name and price, its contents and its option groups. Free groups become the item's contents or a choice the customer makes; priced groups become extras. Adjust the mapping until the preview reads the way a customer would hear it.

Good to know#

• Up to 8 sources per agent.
• A feed larger than the cap is cut at a category boundary and the text says the list continues, so the agent never claims an item does not exist.
• Addresses on private networks are refused.
• Deleting a source also deletes its stored token.