AI
Tools and API connections
Tools are actions an AI agent may take during a conversation: hand over, remember facts, tag, send a location, call a plugin, or call your own API. Open an agent → Tools and switch on the ones it may use.
Built-in tools
| Tool | Does |
|---|---|
| Hand over to the team | Passes the conversation to people when the customer asks or the AI is stuck |
| Recall memory | Looks up what it remembers about the customer |
| Remember facts | Saves preferences and details for future conversations |
| Forget facts | Removes something the customer says is wrong |
| Update profile | Rewrites the short customer profile |
| Update contact | Saves the name, email, phone or attributes the customer gives |
| Tag conversations | Adds one of your workspace tags |
| React to messages | Reacts to the customer's last message with an emoji (channels that support reactions) |
| Set priority | Raises or lowers the conversation priority |
| Resolve conversations | Resolves the conversation, only after the customer confirmed their issue is solved |
| Send locations | Sends a map location, e.g. your store address |
| Send contact cards | Sends a name and phone number as a contact card |
Memory tools need a plan with AI memory.
Tools from plugins
Installed plugins can give your agent tools (check stock, quote shipping, create an order). They show under From plugins; switch each on per agent. See Plugins › AI tools.
API connections
An API connection lets the agent call your own APIs. Secrets stay on the server; the AI only fills the inputs you allow. Hosts, paths and keys stay fixed.
Add one
- Import OpenAPI from a URL or Paste JSON, then Review the operations, or
- Add manually.
Settings
| Field | Meaning |
|---|---|
| Name, Base URL | The API and where it lives |
| Authentication | None, API key header (header name and secret value), or Customer login (a token per customer, kept in the contact's vault) |
| Operations | Each one is a tool: Tool name, Display name (shown in the inbox), Method, Path, When should the AI use this? and Risk (Low, or High (asks first)) |
| Inputs | Per input: key, where it goes (path, query, body or header; streams have no body), required, a description for the AI, allowed values, and how it's filled |
| Answer fields the AI sees | JSON paths it reads from the answer (empty sends the whole answer, trimmed); a Searchable list with fields to search; items per list and characters per answer |
How an input is filled:
| Fill | Value |
|---|---|
| Filled by AI | From the conversation |
| Customer phone, Customer email, Contact ID, Conversation ID | From Beamvia, never from the AI. Customer phone and Customer email can be details the customer only typed, so don't use them to prove who someone is |
| WhatsApp sender phone | The number WhatsApp reports for this chat, which the customer can't change. Use it when an API trusts the number as proof of identity. It's empty on other channels and when WhatsApp hides the number |
| Contact attribute | One of the contact's attributes |
| Fixed value | Always the same (JSON for JSON inputs) |
| Generated secret | A random value Beamvia makes |
Streams
A stream is a live feed (server-sent events) the AI can wait for after a call: "tell me when the payment arrives", "tell me when the email comes in". Waiting costs no AI.
- Stream URL, Login (none, or same as the connection, sent in a header or query), When should the AI start listening?
- Only events where: conditions on event fields (exists, equals, not equals, contains, is one of), and Event fields the AI sees.
- On each event and When it ends without finishing: AI tells the customer, Note for the team, Send a template or Nothing, with an instruction.
- Limits: minutes, max events, debounce, idle stop, reconnects, Stop after the first matching event; Stop listening when a condition holds.
- Extra hosts the stream may connect to (public addresses only).
The Tools tab shows active listeners with Stop all. The conversation shows Listening, Done listening and why a listener stopped.
Every call is logged
API calls show in the conversation (name, result, time). Open one for the arguments from the AI, what it got back, the request, the response and the log. Secrets are hidden; logs are kept 30 days. A refused call shows why.
Plans limit API connections and active listeners.
FAQ
Can the AI call any URL?
No. Only the operations you defined, on the connection's base URL and extra hosts, with the inputs you allowed.
What does High risk do?
The AI asks the customer to confirm before it runs the operation (a payment, a cancellation).
Does the AI ever see my API key?
No. Secrets stay on the server and are hidden in logs.