> ## Documentation Index
> Fetch the complete documentation index at: https://cntillion.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# AI agent custom tools: call your API
> Let your Centillion agent call your API, run a function on your website or app, show interactive cards and book Cal.com meetings. Set up a tool.
Tools let your agent do things during a conversation instead of only
answering from its knowledge. This page covers the AI agent custom tools API
calls, website and app functions, and interactive cards, plus the built-in
tools that sit in the same catalog under **Tools**.
An agent's Tools page lists its attached tools beside built-in capabilities. MCP servers have their own tab.
## Manage an agent's tools
Open **Tools** in the agent sidebar. The **Tools** tab lists the agent's
attached tools and configured actions; **MCP** lists its connected servers.
Search by name or description and filter by type or creator.
**Add tool** opens a searchable picker beside the button. Select an existing
workspace tool to attach it, or choose **New tool** and select **Webhook**,
**Client**, **Code**, or **Integration**. A new tool is saved in the workspace
and attached to the agent together. In **MCP**, choose **Add server**, then
select a saved server or **New custom MCP server**.
Click an attached tool to edit its configuration without leaving the agent.
The editor includes typed parameters, dynamic variables, response assignments,
mock responses, voice execution settings, JSON editing, testing and logs for
the supported tool type. Saved MCP servers can discover tools and select
which ones the agent may use. Tool admins can also manage sharing.
These definitions are shared. Editing one updates the shared tool wherever it
is used. **Remove from agent** only removes this agent's attachment; the tool
remains in the workspace library. Configured actions keep their enable switch,
channel settings and **Customize** control.
## System tools
**System tools** contains nine built-in actions, such as ending a call and
transferring it to a person. They need no API or code. See
[System tools](https://cntillion.com/docs/agents/system-tools.md) for what each one does and how to set it up.
## What it does
* **Call API** sends a request to your HTTPS endpoint and gives the JSON
response to the agent. The response can be up to 20 KB, and you choose which
of its fields the agent sees, up to 200.
* **Run client-side code** calls a function registered on your website through
the JavaScript embed, or in your app through the iOS or Android SDK. A website
function has 20 seconds to finish; an app handler has 25.
* **Call API + show widget** and **Show widget** show an interactive card in
chat, built as a React component, with your API's data or the details the
agent collected.
* The same catalog holds built-in tools: Cal.com bookings, Stripe billing,
Shopify, Twilio, escalations, live chat handoffs and Slack alerts.
* Your plan sets how many tools can be enabled per agent: none on Free, five
on Hobby, eight on Standard and twelve on Pro.
## What you need
* A paid plan with room for another enabled tool. Saving a draft does not
enable it or consume credits. See [plan limits](https://cntillion.com/docs/workspaces/billing.md).
* Message credits: each model request in a tool's tool loop consumes credits
at the selected model's rate.
* The Owner or Member role. Viewers can read tools, and see placeholders in
place of encrypted values. See [workspace roles](https://cntillion.com/docs/workspaces/members.md).
* For **Call API**, an HTTPS endpoint that returns JSON. For website functions,
the JavaScript embed on your site. For app functions, the iOS or Android SDK.
If you are new to the product, start with [what Centillion is](https://cntillion.com/docs/introduction.md).
## Set it up
**1. Open the catalog**
Open **Tools**, then **Add tool**, **New tool**, **Integration**, and choose
**Custom tools**. Give
the tool a name and explain when the agent should use it. Turn on **Only
use in procedures** if a procedure should control when it runs.
The integration catalog includes Escalations, Custom tools and Collect leads.
**2. Choose a type**
Pick **Call API**, **Run client-side code**, **Call API + show widget** or
**Show widget**. The builder shows only the steps your type needs.
**3. Add inputs**
Add named, typed inputs for the information the agent should collect.
Describe each input so the agent knows what to ask the customer.
**4. Connect the request, function or widget**
For an API, enter the URL and request, then choose **Test response**. For a
website function, continue to **Client setup** and copy the code. For a
widget, add one from the gallery or the code editor.
**5. Choose data access**
Keep **Full data access**, or choose **Limited data access** and select the
fields the agent may see.
**6. Pick channels and save**
Turn on the channels where the tool runs. Choose **Save** to keep a new
tool as a draft, or **Save & enable** when it is ready. **Publish** the
branch to use the saved configuration in new customer conversations.
| Type | Behavior |
| - | - |
| Call API | Calls your HTTPS endpoint and gives the JSON response to the agent. |
| Run client-side code | Calls a function registered on your website through the JavaScript embed, or in your app through the iOS or Android SDK. |
| Call API + show widget | Calls your endpoint and shows the returned data in an interactive card. |
| Show widget | Shows a card using inputs collected from the conversation, without calling an API. |
## Use it every day
### API requests and secrets
Enter an HTTPS URL, then use **Add variable** to insert an input such as
`{{order_id}}`. Query parameters also appear in the parameter editor. GET
requests have no body; other request bodies must be JSON. An input in the URL
path can't point the request at another path on your API: a value that makes a
whole path segment `.` or `..`, or that contains `/` or `\`, is refused before
the request is sent. Put values like these in a query parameter instead.
Put API keys in a header or a query parameter, never in the body. Centillion
encrypts header values and any parameter value with text other than an input
like `{{order_id}}`. After you save, the builder shows a placeholder in their
place, and Viewers see a placeholder for the body too.
Requests identify themselves as `Centillion/1.0 (+https://cntillion.com)` in
the `User-Agent` header, so your firewall can allow them. A `User-Agent` header
you add yourself replaces it.
**Test response** takes separate sample input values. The result shows the HTTP
status, duration, response size, headers and body. **Continue** becomes
available after a successful response with valid JSON no larger than 20 KB.
Changing the request or its test inputs clears the previous result, so run the
test again before continuing.
You can instead provide an example JSON response within the same size limit.
The builder shows an error for an invalid or oversized example. An example helps
configure the tool; at execution time the real endpoint is called.
### Data access
The response table shows each field's name, sample value and size. **Limited
data access** adds a checkbox per field, a select-all checkbox and a preview of
the filtered response and its size. Unselected fields are removed before the
response reaches the agent or its widget.
You can select nested fields, fields across array items, empty objects and
arrays, or a response containing a single value. Sizes count UTF-8 bytes, so a
non-ASCII character can take more than one byte. Deselecting every field sends
no response data to the agent. Saved fields missing from a later sample remain
selected until you remove them.
If no response is available, follow the setup button back to the API or test
step. **Save and continue** accepts your access settings for this editing
session. **Skip** restores the last accepted settings, including restrictions
already saved on the tool. The final **Save** or **Save & enable** persists
the changes.
### Website functions
Choose **Run client-side code** and keep **Wait for response** on when the agent
needs the function's result. Add the parameters in **Inputs**, then continue to
**Client setup**. **Copy embed code** installs the JavaScript embed, and **Copy
code** gives a registration template with your exact tool name. Replace the
example with your website's function.
Client tools run functions you register on the host website. Code pasted into
the dashboard never runs. The template queues registration even when the embed
is still loading. For a tool named `get_weather` with a `location` input:
```html theme={null}
```
Register all your tools in one `registerTools` call; each call replaces the
previous registrations. Tool names must match exactly, including case. Use the
current embed snippet from the builder to receive user context. Its version
number, `embed.js?v=10` today, bypasses older cached loaders.
Each function receives `args`, the typed inputs the agent collected, and `user`,
the visitor context:
| Field | Available when |
| - | - |
| `anon_user_id`, `centillion_anon_id` | Every invocation. Internal anonymous visitor identifiers. |
| `user_id` | The server verifies the customer's signed identity. |
| `user_hash` | The identity was verified with a user ID and HMAC hash. JWTs are never exposed to tool handlers. |
| `user_metadata` | Your website supplied metadata in `centillionSettings` or an `identify` call. This data is not identity verification. |
To pass metadata alongside your existing signed identity, call
`window.centillion("identify", { user_id, user_hash, user_metadata: { company: "Acme" } })`.
`window.Centillion("identify", ...)` also works once the widget has loaded; before
that, only the lowercase `window.centillion` queues the call. Generate the signature on
your server, as [identity verification](https://cntillion.com/docs/customer-data/identity-verification.md)
describes. Without valid verification, the handler receives anonymous IDs and
any website metadata, without a customer ID or hash. `logout` and `shutdown`
clear the metadata as well as the identity.
Return `{ status: "success", data: result }` on success, where `data` can be a
JSON value, object or array. Return `{ status: "error", error: "A useful message" }`
on failure. Thrown errors are also returned to the agent. Keep the complete
response below 20 KB and finish within 20 seconds.
With waiting off, the agent receives a dispatch acknowledgment, which does not
confirm that the function finished. A missing function or a timeout returns an
error. Test website functions on the page that loads your embed: they cannot run
in Playground, tool preview or Compare, and the builder preview sends you to
your website instead.
[Event listeners](https://cntillion.com/docs/developer-guides/event-listeners.md) observe website and server
tools with `tool-call` and `tool-result`. Match the call's `id` to the
result's `toolCallId`. A website function can finish after the AI replies when
**Wait for response** is off; its result event still arrives when it finishes.
### App functions
In a native app, register a handler whose name exactly matches the tool name
with the SDK's `tool` method. The SDK runs the handler when the agent calls the
tool and sends back its JSON result, which must be smaller than 20 KB. A call
with no registered handler returns an error to the agent. With **Wait for
response** on, the handler has 25 seconds to answer; after that the agent tells
the customer the tool could not be completed.
### Widgets
Add a widget from its gallery or code editor. Export a default React component
that accepts `data`. For API widgets, `data` is the filtered response. For
widget-only tools, it contains the collected inputs. The preview runs your
component, including its buttons and state changes.
```jsx theme={null}
import { useState } from "react";
export default function OrderCard({ data }) {
const [expanded, setExpanded] = useState(false);
return (
Order {data.order_id}
{expanded &&
{JSON.stringify(data, null, 2)}
}
);
}
```
Widgets run in an isolated frame and support React imports. A declared widget
function can be called with `callFunction(name, values)`. It makes an HTTPS
request from the browser, so the endpoint must allow CORS. Keep API secrets on
your server, out of widget code.
### Channels and saving
Configured channels have switches. Expand **Unconfigured channels** for links
to connect a channel or open its setup guide. API tools can run on supported
messaging channels; client functions and widgets need a browser channel or the
iOS or Android SDK. Upgrading a plan does not make an incompatible channel
available.
Salesforce and Zendesk show a plan lock unless your workspace has the required
entitlement; the upgrade link opens the plans. Channel availability also depends
on whether that channel has a working deployment.
**Save & enable** needs at least one selected channel that is configured,
compatible with the tool type and available on your plan. Saving an existing
enabled tool keeps it enabled. Test the tool in the channel where customers
will use it before relying on it in a live flow.
### Shared tools across agents
Create reusable tools from **Tools** in the workspace sidebar: webhook, client,
code and MCP tools. To reuse one in an agent, open **Tools → Add tool**, search
by name, description or tool ID, filter by type or creator, and select the tool
to attach it; tools already attached show a check mark, and you can add several
before closing the picker. MCP servers are added the same way from the **MCP**
tab with **Add server**. The picker shows the tools you have permission to use,
and Owners and Members can add them.
Attached tools appear on the **Tools** tab with their type, such as **Webhook
tool**. The **…** menu edits the tool (or views it, without edit access), copies
its ID, opens it in the workspace library, or chooses **Remove from agent**,
which detaches the tool from the selected branch draft and keeps it in the
workspace. A tool a teammate attached without sharing it with you still runs in
conversations: the **Tools** tab says how many there are, and the creator or a
workspace Owner can give you access. See
[shared tools and workflows](https://cntillion.com/docs/agents/releases-and-workflows.md).
Individual custom tools keep their configuration and enabled state in published
versions. Disabling or removing one from your draft does not change those
versions. Publish the change for new conversations. Archiving a workspace tool
stops its execution in every version.
### Cal.com bookings
Select **Cal.com** in the integration catalog (**Tools → Add tool → New tool → Integration**) to let customers book a
meeting inside chat. Enter the public event URL, such as
`https://cal.com/your-name/demo`, and give the tool a name. Personal, team and
organization event links work without connecting a Cal.com account or entering
an API key.
Describe when the agent should offer a booking, or turn on **Only use in
procedures** to restrict it to an activated procedure. **Reset** restores the
default booking instructions. With those instructions, a request without dates
searches from today through 28 days ahead; a specified date window can span up
to 31 days. Choose **12-hour time format** if you prefer `1:00 PM` to `13:00`.
Enable the tool on **Chat bubble**, **Help page** or **Center Stage**, the
three browser channels Cal.com tools support, then choose **Save & enable**.
The customer chooses a day, time and time zone in the calendar, enters their name
and email, and selects **Confirm booking**. The form also supports phone number,
notes, guests and a reschedule reason, using the event's visible field settings
when available. Events requiring other custom fields may reject the booking.
Availability is checked again before submission, so a time that someone else
booked cannot be confirmed from an old calendar.
> [!WARNING]
>
> The builder preview and Playground use live Cal.com availability. Selecting
> **Confirm booking** there creates a real appointment, just as it does in a
> customer conversation.
**Meeting booked** means Cal.com accepted the booking. **Booking requested**
means it is awaiting the host's approval. If the result is uncertain, check the
confirmation email before trying again; the same calendar blocks another
submission while that booking is unresolved.
### Stripe tools
[Stripe billing](https://cntillion.com/docs/customer-data/stripe.md) has four built-in tools for invoices,
subscriptions, subscription management and customer information. Connect Stripe
and link verified customer contacts, then select **Stripe** in
the integration catalog (**Tools → Add tool → New tool → Integration**). The subscription tool has plan, quantity, proration and
cancellation settings. Stripe tools run in Chat bubble only; customers confirm
changes in Stripe's hosted portal.
### Shopify tools
The [Shopify integration](https://cntillion.com/docs/channels/shopify.md) has its own tool builder for
products, carts, orders, returns, exchanges and customer accounts. Connect the
store first, then select **Shopify** under **Tools**. These tools need no
custom API request or registered website function. Free orders must be
restricted to a procedure. New-order exchanges require Helpdesk and an
administrator's approval in **Channels → Shopify** before a replacement is
created.
### Twilio tools
With [Twilio connected](https://cntillion.com/docs/channels/phone.md), select **Twilio** in
the integration catalog (**Tools → Add tool → New tool → Integration**) and choose what the tool does:
| Tool | What the agent can do |
| - | - |
| **Send message** | Text the customer by SMS, or MMS with media links |
| **Get message** | Look up one message by its SID |
| **List messages** | List recent messages, newest first |
| **Delete message** | Delete a message from your Twilio records, once the customer confirms |
| **Get call** | Look up one call by its SID |
| **List calls** | List recent calls, newest first |
| **Get messages for number** | List the messages to and from a number |
| **Get calls for number** | List the calls to and from a number |
Under **Phone numbers**, choose whose numbers the tool can use:
* **The customer's own number** (the default). The tool only works for a
verified customer whose contact has a phone number in international format,
such as `+14155550123`. Texts go to that number, and lookups only return that
number's messages and calls. Anonymous visitors are refused.
* **Any number**. The agent uses any number the conversation names. Anyone who
can chat with the agent could then read another person's messages or text a
stranger, so use it only for an agent your customers cannot reach.
**Send message** also needs the number texts are sent from, chosen from the
numbers in your Twilio account that can send SMS, and a limit of 1 to 10 texts
per conversation (3 by default). A retried request never texts twice.
Twilio tools run in the Chat bubble, on the Help page and through the API.
They do not run during phone calls, on messaging channels such as WhatsApp, or
in the Playground, so a test never texts anyone. Disconnecting Twilio turns them
off.
### Phone transfers
Open **Tools**, choose **Transfer to phone number**, and enter the number of
the person or team who should receive the call. Add when the agent should
transfer, its message before connecting, and what it should say if the
transfer fails. Choose the channels, save the tool, and publish the agent.
The **Set up in Tools** button on Pulse's **Transfer to human** card opens
this setup directly. The card shows recorded handoffs for the selected period,
including live chat and ticket escalations. To send callers to different
destinations on different conditions, use
[Transfer to number](https://cntillion.com/docs/agents/system-tools.md#transfer-to-number). For transfers
inside a workflow, see
[phone transfer steps](https://cntillion.com/docs/agents/releases-and-workflows.md#design-a-workflow).
### Human support tools
The catalog includes **Escalations** for follow-up tickets and **Centillion live
chat** for handing the conversation to a teammate, so a person takes over from
the [helpdesk inbox](https://cntillion.com/docs/helpdesk.md). Configure these built-in tools from their own
cards and enable Centillion Helpdesk in their setup. Each has its own channel
selection and **Only use in procedures** setting. A procedure that uses live
chat needs the tool enabled on that channel and Helpdesk turned on. See
[Centillion live chat](https://cntillion.com/docs/helpdesk.md#centillion-live-chat).
For [Salesforce support](https://cntillion.com/docs/helpdesk.md#salesforce-support), choose Salesforce in
**Create ticket** to create a case or escalate the existing native case.
**Salesforce live chat** has its own builder for Chat bubble, Help page and
Center Stage handoffs to Salesforce Enhanced Chat. Connect Salesforce and enable
Helpdesk before enabling these tools.
To alert your team without handing the conversation off, use the **Slack**
tool. It posts a summary and a link to the conversation in a Slack channel,
and the agent keeps helping the customer. An agent has one Slack tool, which
posts to one channel. See [Conversation
notifications](https://cntillion.com/docs/channels/slack.md#conversation-notifications).
### Send captured data to Zapier
Collect leads, Collect data and custom form submissions can start a Zapier
workflow. Open **Channels → Zapier**, connect your agent, and select the **Form
Submission** trigger in Zapier. Map contact and custom fields into your CRM,
spreadsheet or another destination. See [Zapier](https://cntillion.com/docs/channels/zapier.md) for the
complete setup and a Google Docs example.
## Limits and good to know
* API responses, website function results and app results must each stay under
20 KB.
* Limited data access selects up to 200 fields.
* Website functions finish within 20 seconds; app handlers answer within 25
seconds when **Wait for response** is on.
* Website functions cannot run in Playground, tool preview or Compare.
* Cal.com tools run on Chat bubble, Help page and Center Stage. Stripe tools
run in Chat bubble only. Twilio tools run in the Chat bubble, on the Help
page and through the API.
* Enabled tools per agent: Free none, Hobby five, Standard eight, Pro twelve.
## Questions
### Where do I keep the API key for my endpoint?
In a header or a query parameter, never in the body. Centillion encrypts header
values and parameter values that are more than a plain input reference, and the
builder shows a placeholder after you save.
### Can I test a website function in the Playground?
No. Website functions run only on a page that loads your embed, so test them on
your website. The Playground, tool preview and Compare send you there.
### What does the agent see from my API response?
With **Full data access**, the whole response. With **Limited data access**,
only the fields you selected, up to 200. Unselected fields are removed before the
response reaches the agent or its widget.
### Does a Cal.com test booking create a real appointment?
Yes. The builder preview and Playground use live availability, and **Confirm
booking** creates a real appointment there just as it does with a customer.
### Why can't I enable a tool on a channel?
The channel may not be configured, may not support the tool type, or may need
a plan your workspace does not have. Client functions and widgets need a browser
channel or a mobile SDK, and upgrading does not change that.
### Do tools work in published releases?
Published versions keep each tool's saved configuration and enabled state.
Disabling or removing a tool from your draft changes new conversations after
you publish. Archiving a workspace tool stops its execution in every version.
## Try it
Start with one **Call API** tool against a read-only endpoint, such as an
order lookup, and test it on the channel your customers use.
> [card] [Start free](https://app.cntillion.com/sign-up?utm_source=docs\&utm_medium=article\&utm_campaign=agents-custom-actions)
>
> Start on the Free plan, or take a seven-day trial of a paid plan. Your agent is live on your site in an afternoon.
> [card] [Book a demo](https://cal.com/patrick-turricelli-smgfks/15min?utm_source=docs\&utm_medium=article\&utm_campaign=agents-custom-actions)
>
> Fifteen minutes with the team, on your own use case.
Or ask the assistant on this page.
## Related
> [card] [What Centillion is](https://cntillion.com/docs/introduction.md)
>
> How the agent, its knowledge and its channels fit together.
> [card] [Collect data](https://cntillion.com/docs/agents/collect-data.md)
>
> Ask for structured details in chat and send each submission on.
> [card] [Zapier](https://cntillion.com/docs/channels/zapier.md)
>
> Start a Zap from each lead or form submission.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.