Integrations

Connect your AI agents to external systems with custom HTTP tools, manage API keys securely with the secrets manager, and test tools directly from the dashboard.

Integrations extend your agent's capabilities beyond answering questions from the Knowledge Base. With custom HTTP tools, your agent can call external APIs during a conversation — look up live data, check stock, fetch order status, or trigger workflows in other systems.

You manage integrations under Integrations in the sidebar. The page has two tabs:

• Tools — Custom HTTP tools your agents can call.
• Secrets — Encrypted API keys and credentials, referenced from tools as $secret:key.

Tools and secrets are defined once per organization and shared across all agents. Each agent then chooses which tools it actually uses (see Attaching Tools to Agents).

Who Can Do What

Members do not see the Integrations entry in the sidebar and are redirected to Chat if they open the URL directly. Builders can view everything and wire existing tools into agents, but creating or changing tools and secrets requires the Admin or Owner role.

Built-In Tools

Besides custom HTTP tools, agents have a small set of built-in tools. These are configured in the agent editor (Configure tab), not on the Integrations page:

Custom HTTP Tools

A custom tool is an API endpoint your agent can call when it decides the action fits the conversation. You create tools on the Tools tab via New Tool.

Tool Configuration

Parameters

You define parameters as rows in the form, each with:

• Name — The argument name your API expects.
• Type — string, number, integer, or boolean.
• Description for the AI — Explains what value the model should extract from the conversation (e.g. "The order number the customer mentions, digits only").
• Required — Whether the model must always provide this argument.

The parameters become the tool's function signature: the model reads the names, types, and descriptions to decide which values to pull from the conversation. Precise descriptions directly improve how reliably the agent fills in arguments.

Authentication

Token, password, and header-value fields all accept $secret:key references, and each field has a $secret picker chip that inserts one for you. Always store credentials as secrets instead of pasting them in plain text.

How Requests Are Sent

• GET and DELETE — Tool arguments are sent as URL query parameters, merged with any query string already in the endpoint.
• POST, PUT, and PATCH — Tool arguments are sent as a JSON request body.
• Path variables — If the endpoint contains {param} and the model provides a matching argument, it is substituted into the URL and removed from the remaining arguments. Example: https://api.yourshop.com/orders/{order_id} with order_id: 1234 becomes https://api.yourshop.com/orders/1234.
• Secrets — $secret:key references in the endpoint URL, headers, and auth fields are resolved at call time. If a referenced secret does not exist, the placeholder is sent as literal text.
• Timeout — Live calls time out after 30 seconds.

Responses and Error Handling

• Success (2xx) — The response body is passed to the model as-is (JSON is serialized, plain text stays plain text). The agent uses it to formulate its answer.
• HTTP errors (4xx/5xx) — The response body is hidden from the model for security. The agent only sees The external API returned HTTP <status>. — never the error details.
• Connection failures — The agent sees a generic The external API call failed.

This means: anything you want the agent to read and relay to the customer must come back with a 2xx status code. For example, if a product is out of stock, return 200 with {"in_stock": false, "restock_date": "2026-07-01"} rather than a 404.

Because HTTP tools can have side effects (booking an appointment, creating a ticket), the platform never automatically retries them or re-runs a conversation turn after one has executed.

Security: Blocked Endpoints

To prevent abuse, custom tool endpoints are restricted:

• Only http:// and https:// URLs are allowed.
• Before each call, the endpoint hostname is resolved and checked. Endpoints that point to private networks, localhost, link-local or cloud-metadata addresses, or other internal/reserved ranges are blocked, as are hostnames that fail to resolve.

A blocked call returns Endpoint blocked by security policy. In plain terms: your tools can reach the public internet, but not internal or private hosts. If you need to integrate dedicated or internal infrastructure, see Managed Tools.

Testing a Tool

Every tool row has a Test (play) button that opens the Test Tool modal:

1. The Parameters (JSON) field is pre-filled with a sample generated from your parameter schema.
2. Adjust the values and click Run Test. This makes a real call to your endpoint with secrets resolved, authentication applied, and path variables substituted (test calls use a 10-second timeout).
3. The result shows the status code, the response body, and the resolved URL. In the resolved URL, secret values longer than 3 characters are redacted to their first 3 characters plus ***. The response body is shown verbatim — if the tested endpoint echoes the request back (e.g. reflects the Authorization header or query parameters), the full secret value appears in the result.

Testing requires the Admin or Owner role. Once the direct test passes, use the agent's test chat for an end-to-end check — verify the agent picks the tool at the right moment and extracts the parameters correctly.

Example: Stock Checker

When a customer asks "Is the blue garden hose in stock?", the agent:

1. Recognizes the intent matches the tool's description.
2. Extracts the parameters (product_name: "garden hose", variant: "blue").
3. Calls GET https://api.yourshop.com/stock?product_name=garden+hose&variant=blue with the Bearer token.
4. Uses the response to formulate a natural answer: "Yes, the blue garden hose is in stock. We have 12 units available."

Example: Order Status with a Path Variable

The order_id the model extracts is substituted into the URL path before the call.

Attaching Tools to Agents

Tools live at the organization level; each agent picks the ones it uses:

1. Open the agent in the agent editor (Configure tab).
2. Expand the HTTP Tools section. It lists every tool in your organization with a toggle switch per tool, and the section header shows how many are active.
3. Toggle on the tools this agent should use.

If no tools exist yet, the section links to the Integrations page. Builders can attach and detach tools here even though they cannot create new ones.

A tool can also be disabled globally for the whole organization — it then shows a Disabled globally badge in the agent editor and is skipped by every agent until re-enabled, regardless of the per-agent toggles. There is currently no dashboard switch for this global flag; it is only available through the API.

Managed Tools

Tools have a Type: HTTP (external) or Managed. Managed tools are provisioned by botts.ai platform staff for dedicated or internal infrastructure — for example, an ERP or factory bridge running in your environment. Compared to regular HTTP tools, managed tools:

• Bypass the private-network blocking, so they can reach internal hosts.
• Automatically retry on connection errors (up to 3 attempts, 1 second apart). Regular HTTP tools never retry.
• Show an amber Managed badge in the tools list.

You cannot create managed tools yourself — the Type selector is disabled for customer accounts. If you need a dedicated integration to internal systems, contact botts.ai.

Secrets

The Secrets tab is the secure store for API keys and other credentials your tools need. Each secret has:

• Name — A display label, e.g. "Acme API Key".
• Key — The identifier you reference in tools as $secret:key, e.g. acme_api_key.
• Value — The credential itself.

Security Properties

• Secret values are encrypted at rest and never leave botts.ai's Swiss infrastructure.
• Values are write-only: after creation, neither the dashboard nor the API ever returns a secret's value. The list shows only the name, key, and scope. In tool test results, resolved secret values are redacted in the displayed URL, but the response body is shown unmodified — an endpoint that echoes the request returns them in full (see Testing a Tool).
• There is no edit function. To rotate a secret, delete it and recreate it with the same key — tools referencing $secret:key keep working without changes.
• $secret:key references resolve in the endpoint URL, header values, and authentication fields at call time.

Scopes

Use org-scoped secrets for any tool an agent uses in live conversations. User-scoped secrets only resolve when you run a tool test yourself from the dashboard — in live agent conversations (widget, internal chat, voice), only org-scoped secrets are resolved.

A duplicate key within the same scope is rejected; pick a unique key per secret.

Integration Best Practices

1. Write clear descriptions — The agent decides when to use a tool based on its description. Vague descriptions lead to the tool being used at the wrong time. The same goes for parameter descriptions: they steer what the model extracts.
2. Keep APIs fast — The agent waits for the API response before continuing the conversation (up to the 30-second timeout). Slow APIs create awkward pauses.
3. Return useful information with a 2xx status — The agent never sees the body of a 4xx/5xx response, only the status code. If "not found" or "out of stock" is something the agent should explain to the customer, return it as a 200 with a descriptive JSON body.
4. Store credentials as secrets — Never paste API keys directly into endpoints or headers; use $secret:key references so they stay encrypted and redacted.
5. Test with the Test button first — Verify the real call, status code, and resolved URL from the Integrations page, then use the agent's test chat to confirm the agent triggers the tool at the right moment.
6. Start simple — Begin with one or two tools and expand as you learn how your agent interacts with them.

Last updated on June 16, 2026