Data Connections
Data Connections let your AI assistant reach into your own systems — an order database, a CRM, an inventory API — to answer questions with real, live data instead of guessing. Connect an endpoint once, and your assistant can look up a customer's order status, check a product's stock level, or (with your approval on every single use) create a support ticket or update a record, all from inside the conversation.
Why Data Connections Matter
- Answer "where's my order?" with your real order data, not a generic reply
- No engineering work per integration — one guided setup wizard, no code
- Test against your real endpoint before anything goes live
- You control exactly which fields the AI is allowed to see
- Actions that change data always require a teammate's approval first
- Built on the same secure request layer for every connection — no per-integration security review needed
Two Building Blocks
Every Data Connection is a link to one of your systems (a base URL plus how to authenticate to it). Underneath a connection, you configure one or more of these:
Data Sources (read-only)
A lookup — "get this customer's profile", "get this order's status". The AI can call these automatically during a conversation, any time it's relevant. Nothing is ever changed in your system by a Data Source.
Write Actions (approval required)
Something that changes data — "create a support ticket", "update a shipping address". The AI can only ever propose one; a teammate has to review and approve it before it actually runs.
Setup Guide
Go to Settings → Apps & Integrations → Data Connections and click Connect a custom endpoint. The wizard walks you through the steps below.
Tell us about your system
Two ways to get started — pick whichever is easier for you:
- I have a setup link — paste a public OpenAPI/Swagger URL and we'll read your available endpoints for you
- I'll enter the details myself — type in the base URL and pick each endpoint by hand
Where is your system, and how do we authenticate?
Enter the base URL of your API and its secret key (Bearer token, API key, or Basic auth). If you imported a setup link, we detect the auth type for you automatically — you just paste the secret.
Your secret key is stored encrypted and is never shown to agents, admins, or the AI — it's only ever attached to the outgoing request, server-side.
Test the connection
We check that your system is reachable before you go any further, so you catch a typo in the URL or a wrong secret key immediately instead of after everything is configured.
Choose what to connect
Pick which endpoints become Data Sources (lookups) and which become Write Actions (approval-required changes). If you imported a setup link, every endpoint is listed for you to select from — you don't need to type URLs by hand.
Configure how a customer is matched
For each Data Source, tell us how to identify which customer a lookup is for:
- Email or Phone — automatic. We use the customer's already-verified contact info, never anything they simply typed in the chat.
- Something else, I'll set it up manually — the AI extracts a value straight from the conversation (see "Extra values" below).
Try it with a real example
Run a real test call right there in the wizard — enter a sample value and see exactly what your system sends back. Tick which fields the AI and your agents should be able to see, give each one a friendly label, and that becomes your output mapping. No manual copying of field names required.
If the test fails, we show you the exact response your system sent back (status code and body) — so you can tell a wrong URL apart from a bad secret key apart from a missing field, instead of just seeing "unreachable".
Review and finish
A plain-language summary of what your assistant can now look up and propose — with an edit link for anything you want to change. Nothing technical to double-check.
Extra Values — Letting the AI Extract Details From the Message
Beyond identifying who the customer is, a lookup often needs a specific detail from what they typed — an order number, a product ID, a ticket reference. Extra values tell the AI what to look for and where to put it.
How to set one up
Give it a key (e.g. orderNumber), a type, and — importantly — a short description of what it means, e.g. "the order number the customer mentioned, e.g. ORD-1234". That description is what the AI reads to know what to pull out of a free-form message, so a clear description directly improves accuracy.
When it's required vs. optional
If you chose manual customer matching, at least one extra value is what makes the lookup vary per customer at all — without one, the same request would run for everyone. If you chose Email or Phone matching, extra values are a genuine add-on (e.g. combining "which customer" with "which order") and live under Advanced settings since most connections don't need them.
How Customer Identity Stays Safe
One rule never bends: a customer's email or phone number is only ever taken from their already-verified contact record — never from something they typed in the chat.
If that weren't the case, anyone could type someone else's email into the chat and pull up their private order history or account details. Extra values are safe to extract from free text because they're a lookup filter, not proof of who someone is — identity resolution and free-text extraction are kept deliberately separate for this reason.
Output Field Mapping
You decide exactly which fields from your system's response the AI and your agents can see — everything else your API returns stays server-side and is never shown to anyone. Pick fields straight from a real test response (step 6 above) or add them by hand with a JSON path and a friendly label. It's fine to leave this empty at first and add fields later.
Advanced Settings (Optional)
Sensible defaults are prefilled for every connection — most admins never need to touch these. They're tucked under an "Advanced" section so setup stays simple for non-technical users.
AI-callable
On by default — the AI can use this Data Source automatically during a conversation. Turn it off for a lookup you only want your team to trigger manually.
Cache duration
How long a successful result is reused before looking it up again (2 minutes by default) — useful for data that doesn't change every second, and reduces load on your system.
Default selection
For lookups that can return multiple records, choose whether to automatically use the first match or have the agent pick when there's more than one.
Enabled
Turn a Data Source off entirely without deleting its configuration — useful while an integration is temporarily down on your end.
How the AI Decides What to Use
Your assistant doesn't call every connected system on every message — it reasons about relevance first.
Customer sends a message
Fiko checks whether any AI-callable Data Sources or Write Actions are configured for your company at all. If none are, this step is skipped entirely.
Relevance check
The AI reads the conversation and each connection's description to decide whether anything is actually relevant — most messages ('thanks!', 'ok') trigger no lookup at all.
Extraction
If a lookup is relevant, the AI fills in any required extra values it can confidently find in the conversation, using the descriptions you wrote for each one.
Lookup or proposal
Data Sources are called automatically. Write Actions are only ever proposed — sent to a teammate for a look before anything actually runs.
Grounded reply
The AI's response is generated using the real data that came back, through your output field mapping — not invented.
Built-In Security
Every request is protected
Every call Fiko makes to your system — during setup testing or live in a conversation — goes through the same hardened request layer: it re-verifies the destination right before connecting, never follows a redirect, and times out quickly. This applies uniformly, so there's no per-connection security setup for you to get right.
Credentials stay yours
Your API secret is encrypted at rest, attached to outgoing requests only, and never rendered in any admin screen, log, or AI prompt after you save it.
Only what you map, ever leaves
The AI and your agents only ever see the fields you explicitly picked in output field mapping — the rest of your system's response is discarded after the call, on every single lookup.
Changes always need a human
Write Actions can never execute on their own — the AI proposes, a teammate approves or rejects, every time. There is no setting that removes this step.
Best Practices
Do
- Write a clear description for the connection — it's what the AI uses to decide relevance
- Write a clear description for every extra value — it directly drives extraction accuracy
- Test with a real example before finishing setup
- Map only the fields agents and the AI actually need
- Start a new connection with AI-callable on, and turn it off later only if needed
Don't
- Leave a manual-matching connection with zero extra values — it can't vary per customer
- Map fields you don't actually want customers' questions answered with
- Expect a Write Action to run without a teammate approving it — that's by design
- Reuse one connection's secret key across unrelated systems
- Assume every message triggers a lookup — irrelevant messages correctly trigger none
Troubleshooting
Test says "unreachable" with no explanation?
- Check the exact status code and response body now shown under the test result — a 401 means a bad secret key, a 404 means a wrong path, a 400 usually means a missing or malformed value
- Confirm the base URL has no typos and doesn't include a path that belongs in the endpoint's URL template
- Make sure your system is actually publicly reachable from the internet, not just your office network
The AI isn't using a connection I set up?
- Check that AI-callable is turned on for that Data Source
- Make sure the description clearly explains when it's relevant — vague descriptions get skipped
- Remember: most messages correctly trigger no lookup at all — try a message that clearly needs the data
The AI extracted the wrong value from the message?
- Make the extra value's description more specific, with an example format (e.g. "an order number like ORD-1234")
- Check that the key name itself is self-explanatory, not something ambiguous like "code" or "ref"
- Mark the value as required only if a lookup genuinely can't run without it
A Write Action isn't showing up for approval?
- Confirm all of its required extra values could be confidently filled from the conversation — an incomplete proposal is dropped rather than sent for approval
- Check that Write Actions are enabled for your company
- Verify the connection and Write Action are both still marked enabled