Data connectors: the assistant reads live data from your API
Articles and files answer general questions. A customer often asks about their own case: "Where is my order 104233?", "Is my booking for Friday confirmed?". Data connectors let the project's AI assistant ask your own system through its API and answer with live data. This guide covers how a connector is built, how to set it up step by step, how to import a request from cURL, how to check it, and what protects your data.
Data connectors work with the Sensever model under "Who answers customers" in the project's "Assistant" tile, in the "Data connectors" block between "Files and tables" and the "Test chat". They are configured by the project's owner and admins. The rest of the assistant's settings are described in Project AI assistant: setup, knowledge and hand-over to your team.
How it works
A connector has two levels:
A connection is your API as a whole: its base address, for example
https://api.shop.com/v1, and the authorization. You enter the key once, in the connection.Methods are the requests inside a connection, for example "Order status" =
GET /orders/{order_id}. A method doesn't ask for the key again: the connection's key and common headers are added to every request.
The model decides by a method's "When to use" text whether to call it. When a customer's question matches, the assistant collects the parameters (asks the customer for the missing ones), Sensever sends the request to your API, takes the response fields you chose and gives them to the model, and the model writes the answer. One answer can call up to 4 methods.
Connectors only read data. A method is either GET or a POST that only searches or reads. Actions that change data, such as creating an order or cancelling a booking, are not available to connectors yet.
Add a connection
In the "Data connectors" block, click "Add connection".
Connection name: a short name your team will recognise, for example "Shop".
Base address: the common part of all requests to this API, only
https, for examplehttps://api.shop.com/v1. Methods add their path to it.Authorization: choose the "Type" your API uses: "None", "API key in a header" (also enter the "Header or parameter name", for example
X-Api-Key), "API key in the address" (the name of the address parameter, for exampleapi_key), "Bearer token", or "Login and password (Basic)" (also enter the "Login").Key, token or password: paste the secret. It is stored encrypted. After saving only a mask is shown ("Saved: ••••1234 — leave empty to keep it"): leave the field empty to keep the saved key, or paste a new one to replace it.
Common headers (optional): headers sent with every method of this connection, for example
X-Shop-Id. Keys and passwords don't go here:AuthorizationandCookieheaders are refused, use "Authorization" instead.Check path (optional): a light address for checking the connection, for example
/healthor/me. Empty means the base address itself is requested.Limits: "Timeout, seconds" (8 by default, up to 15) and "Calls per minute" (30 by default, up to 120). The call limit is shared by all methods of the connection, because an API usually has one key and one quota.
Click "Check connection": Sensever sends a real GET request with your key and shows the status, the time, the address with the secret masked, and the beginning of the response. Then click "Save".
The connection appears as a card: its switch ("Connection on"), name, host, authorization type, number of methods and the result of the last check or call, with "Check connection", "Edit" and "Delete". Deleting a connection deletes its methods and their call log too.
Add a method
In the connection's card, click "Add method". The form shows the connection's base address and reminds you that the key and common headers are added for you.
Method name: for example "Order status".
When to use: the model decides by this text whether to call the method. Write it the way a customer would ask, for example "When the customer asks where their order is or what its status is".
Request: the "Method" (GET or POST) and the Path from the base address, for example
/orders/{order_id}. Every name in braces becomes a path parameter. For a POST, turn on "This POST only searches or reads data": otherwise it can't be saved.Parameters: for each value, its "Name", where it is "Sent in" (Path, Query, Header or Body), its "Type" (Text, Number, Yes/no, Date), "Required", and where its "Value" comes from: "Ask the customer", "Fixed value" or "From the request" (see below).
Response: "Fields for the model", one JSON path per line, for example
status,delivery.date,items[*].name. Empty means the whole response. Give only what is needed to answer. "Response limit, bytes" (4,000 by default, up to 16,000) cuts what the model gets.Click Check: enter test values for the parameters and send a real request. You see the status, the time, the address and, under "The model will see", exactly the data the model will get. Then click "Save".
Where a parameter's value comes from:
Ask the customer: the assistant asks for it in the conversation, for example the order number. The "Hint for the model" helps, for example "Order number, 6 digits".
Fixed value: the same every time, for example
shop=7.From the request: Sensever fills it in itself: "Customer name", "Customer phone", "Customer email", "Request number", "Customer language" or "Channel (widget, WhatsApp…)". The phone is the customer's WhatsApp number in a WhatsApp request or the contact phone of their Sensever account; the email is a confirmed one. A guest of the website widget has neither, and such a call ends with "The customer's details are unknown".
Only "Ask the customer" parameters are visible to the model. Fixed values and values from the request are added by Sensever when the request is sent.
Each method has its own switch ("Method on"), the last call's result, "Edit" and "Delete". The assistant uses only the enabled methods of enabled connections.
Import from cURL
What cURL is. cURL is a command-line program for sending web requests. Most API documentation shows example requests as curl commands, so a command like this already holds everything a method needs: the address, the key, the parameters.
curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.shop.com/v1/orders/104233?shop=7"Where to get it.
Your system's API documentation. CRMs, shops, booking and delivery services usually show an example
curlrequest next to each method, often with a copy button. Take the example of the method you need and put your key in it.The browser's developer tools. Open the page of your system that shows the data, for example an order card. Open the developer tools (F12, or Cmd+Option+I on a Mac), go to the "Network" tab and reload the page. Find the request that returns the data, right-click it and choose "Copy" → "Copy as cURL" (in Chrome and Edge choose the "bash" variant if there are several). Keep in mind that the browser usually signs in with your session cookies: the import ignores cookies, so such a request works in a connector only if your API also accepts a key or token.
How to import. Click "Import from cURL", paste the command into "curl command" and click "Fill in the form". The command is read in your browser and is not run.
The base address and the key go to the connection, the path and the parameters go to a new method. The authorization is recognised from an
Authorization: BearerorBasicheader,-u login:password, headers likeX-Api-Keyand address parameters likeapi_keyortoken.The other address parameters, headers and JSON body fields become fixed values; parameters with an empty value become "Ask the customer". Review them and decide what the assistant should ask the customer, for example change the order number from a fixed value to "Ask the customer".
If the project already has a connection with the same host and base path, the new method is added to it and its key is not changed. Otherwise the connection form opens with the key from the command; after you save it, the method form opens with the rest.
Call log
"Call log" opens "Connector calls" for the last 30 days: the time, the source ("Customer", "Test chat" or "Check"), the method, the result and the duration. Connection checks appear as rows without a method. The "Connection" filter narrows the log to one connection. Parameter values and response bodies are not stored.
Typical results: "OK", "Nothing found" (the API answered 404), "API error" with its code, "No reply within the timeout", "Could not connect", "Certificate error", "Address not allowed (internal or private network)", "Redirect to another address refused", "Response too large", "Unreadable response", "Call limit reached", "A required value is missing or has the wrong format" and "The customer's details are unknown".
What the customer gets
Data found: the assistant answers with the fields it received.
Nothing found: the assistant says so, for example that there is no order with this number.
A value is missing: the assistant asks the customer for it.
The API failed: the assistant is told that the data is unavailable and offers to pass the question to an operator.
In the test chat, "Sources and tools" lists every connector call with its result and duration. Enter "Customer details for the test" to try methods that take the phone, email or name from the request.
Security
Read only. A method is GET or a POST marked as read-only. Nothing in your system is created, changed or deleted by the assistant.
The model never sees your key. Keys, tokens and passwords are stored encrypted, and after saving only a mask is shown. The key is not put into the model's instructions or tools: the model sees only the "Ask the customer" parameters and the response fields you chose. If your API repeats the key in its response, it is replaced with
[secret]before anything is read. The call log keeps neither addresses nor headers.Only public HTTPS addresses. The base address must be
httpswith a domain name: IP addresses, logins in the address, ports other than 443 and 8443, and internal names such aslocalhostor.localare refused. Before every call the name is resolved again, and every address must be public: private networks, loopback and cloud metadata addresses are refused.A method can't leave its API. A path only continues the base address: it can't contain
https://,//,@,..or#, and values in the path are encoded. A redirect is followed only for GET, only to the same host, at most 3 times; a redirect to another host is refused, so your key never goes elsewhere.Limits. A request has a timeout (8 seconds by default, up to 15), a response over 1 MB is not read, and the calls per minute are limited per connection. Checks are limited too: "Too many checks in a row" means wait a minute.
Only your team configures it. Connectors, checks and the log are available to the project's owner and admins, signed in as themselves. A connector belongs to its project and is never used by another one.
Limits
What | Limit |
|---|---|
Connections in a project | 10 |
Methods in a connection / in a project | 30 / 60 |
Methods the model can use in one answer | 20 |
Method calls in one answer | 4 |
Common headers in a connection | 10 |
Parameters / response fields in a method | 20 / 20 |
Timeout | 8 s by default, up to 15 s |
Calls per minute per connection | 30 by default, up to 120 |
What the model sees from one response | 4,000 bytes by default, up to 16,000 |
Response size read from your API | 1 MB |
Call log | 30 days |
The assistant can be turned on even when data connectors are its only source: one enabled method of an enabled connection is enough.
Комментарийлер