AI agent custom tools: call your API

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.

Agent Tools page with Tools and MCP tabs, search, type and creator filters, attached tools and the System tools panel — 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 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.
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.
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.

Set it up

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.

Integration catalog with search and the Escalations, Custom tools and Collect leads cards — The integration catalog includes Escalations, Custom tools and Collect leads.

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.

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.

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.

Choose data access

Keep Full data access, or choose Limited data access and select the fields the agent may see.

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:

<script>
  window.centillion = window.centillion || function () {
    (window.centillion.q = window.centillion.q || []).push(arguments);
  };
  window.centillion("registerTools", {
    get_weather: async (args, user) => {
      try {
        const response = await fetch(
          "/api/weather?location=" + encodeURIComponent(args.location)
        );
        if (!response.ok) throw new Error("Weather data is unavailable");
        return { status: "success", data: await response.json() };
      } catch (error) {
        return { status: "error", error: error?.message || "Action failed" };
      }
    }
  });
</script>
<script
  src="https://app.cntillion.com/embed.js?v=10"
  data-centillion-agent="YOUR_AGENT_ID"
  defer
></script>

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 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 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.

import { useState } from "react";

export default function OrderCard({ data }) {
  const [expanded, setExpanded] = useState(false);
  return (
    <div>
      <p>Order {data.order_id}</p>
      <button onClick={() => setExpanded(!expanded)}>Show details</button>
      {expanded && <pre>{JSON.stringify(data, null, 2)}</pre>}
    </div>
  );
}

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. 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.

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 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 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, 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. For transfers inside a workflow, see phone transfer steps.

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. 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. For 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.

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 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.

Start free

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.

Book a demo

Fifteen minutes with the team, on your own use case.

Or ask the assistant on this page.

What Centillion is

How the agent, its knowledge and its channels fit together.

Collect data

Ask for structured details in chat and send each submission on.

Zapier

Start a Zap from each lead or form submission.

​Manage an agent’s tools

​System tools

​What it does

​What you need

​Set it up

​Use it every day

​API requests and secrets

​Data access

​Website functions

​App functions

​Widgets

​Channels and saving

​Shared tools across agents

​Cal.com bookings

​Stripe tools

​Shopify tools

​Twilio tools

​Phone transfers

​Human support tools

​Send captured data to Zapier

​Limits and good to know

​Questions

​Where do I keep the API key for my endpoint?

​Can I test a website function in the Playground?

​What does the agent see from my API response?

​Does a Cal.com test booking create a real appointment?

​Why can’t I enable a tool on a channel?

​Do tools work in published releases?

​Try it

Start free

Book a demo

​Related

What Centillion is

Collect data

Zapier

Manage an agent’s tools

System tools

What it does

What you need

Set it up

Use it every day

API requests and secrets

Data access

Website functions

App functions

Widgets

Channels and saving

Shared tools across agents

Cal.com bookings

Stripe tools

Shopify tools

Twilio tools

Phone transfers

Human support tools

Send captured data to Zapier

Limits and good to know

Questions

Where do I keep the API key for my endpoint?

Can I test a website function in the Playground?

What does the agent see from my API response?

Does a Cal.com test booking create a real appointment?

Why can’t I enable a tool on a channel?

Do tools work in published releases?

Try it

Related