Create a Call Action

What it is

Creating a Call Action adds a capability to your chatbot's library. Creating it is not the same as switching it on: an action sits in the library, configured but inert, until you turn on Enabled. That separation exists so a half-finished integration cannot fire at a real customer.

This page walks the whole flow — chooser, editor, sandbox test, enable — and then walks one real integration end to end.

When you would use it

When you want the chatbot to do something beyond answering: show a link, escalate to a person, alert your team, save a contact, or call an API. See What are Call actions? for the difference between the types.

Where to find it

Open Dashboard → Chatbots → your chatbot → Actions, then select New action.

Steps

1. Open the Actions tab and select New action. The chooser opens: "Build from scratch, start from a template, or import an OpenAPI spec."
2. Pick your starting point:
   • Start from scratch — one tile per action type: Button, Human handoff, Notify team, Collect info, Custom API, MCP server.
   • Or start from a template — a searchable gallery of named integrations, each pre-filled. See Use a preset.
   • Import from OpenAPI — paste an OpenAPI or Swagger document as JSON and Agentency turns each operation into a seeded action for you to review and save one at a time. YAML is not accepted; convert it to JSON first.
3. The editor opens as a slide-over with three tabs: Details, Configure, Test.
4. On Details, set the Name (for your team) and When should the AI use this? (for the model — at least 8 characters, and the most important field on the page).
5. On Configure, fill in the type-specific fields. Every type shows a What you'll need panel here with its setup steps.
6. On Test, type a sample visitor message and select Run test. Nothing is sent and nothing is recorded.
7. Return to Details, turn on Enabled, and Save.
8. Open Test Chatbot and ask a question that should trigger it, then check the run log. See Try the test chat.

The Details tab, field by field

Field	What it is for
Name	Your own label. Shows on the library card and in the run log.
When should the AI use this?	Read by the AI model, not the visitor. Describes the situation that should trigger the action.
Enabled	When off, the model is never offered this action. It stays configured but never runs in a real conversation.
Requires confirmation	The chatbot must ask the visitor to confirm on their next message before the action actually runs.
Max calls per reply (optional)	How many times this one action may run inside a single reply, from 1 to 5. Leave blank for the default.

When should the AI use this? deserves the time. The product says so itself in the tab: how reliably actions fire depends on your model's tool-calling support and, most of all, on a clear description. Write it as a situation, not a label:

• Weak: Booking
• Strong: When the visitor asks to book a demo or a call and has given a date, their name, and their email address.

Naming what the visitor must already have supplied ("and has given…") is the trick that stops an action firing before it has anything useful to work with.

Confirmation, and why it is not optional for some actions

Requires confirmation turns a one-step action into a two-step one. The first time the chatbot wants to run it, the visitor gets a short prompt naming the action plus Confirm and Cancel buttons. Only after they reply does the action actually run.

Crucially, the confirmation has to come from a later message. The chatbot cannot satisfy its own confirmation inside the same reply, and neither can text it read from a web page, a document, or an API response. That is the defence against a customer — or a crafted page — talking your chatbot into placing an order or emailing someone.

Templates that create, order, send, or charge ship with this on. Custom API actions using POST, PUT, PATCH, or DELETE are treated as changing data and require confirmation by default even if you leave the switch off. Read-only look-ups do not need it.

Testing before you go live

The Test tab is a genuine sandbox: "Run this action in a sandbox — nothing is sent and no analytics are recorded." No email leaves, no API is called, no run is logged.

Type a realistic visitor sentence and run it. You get back:

• whether the model would trigger the action, with a hint pointing you at the description if it would not;
• the AI reply it would produce;
• the arguments it extracted from your sentence;
• a request preview and response preview for Custom API actions, with secrets masked.

Iterate here — it is much faster than going live and reading run logs. One note: running a test with a sample message makes a real call to the chatbot's testing model, so it only runs while your workspace has message credits left; it is not charged as a reply. Testing with explicit arguments instead of a sample message makes no model call at all. See Message credits.

Walkthrough: an order-status look-up, end to end

A concrete example, from nothing to a working integration. The shape is the same for any read-only API you own.

1. Get the credential first. Whatever your store or system uses — an API key, a token, a key-and-secret pair. Give it read access only. If you are following a template, the What you'll need panel names the exact scope.

2. Create the action. Actions → New action → Custom API (or the matching template).

3. Details.

• Name: Check an order
• When should the AI use this?: When the visitor asks about the status of an order they placed and has given the order number.
• Requires confirmation: off — this only reads.

4. Configure — the request. Method GET, and an address with a placeholder where the order number goes:

https://api.example.com/v1/orders/{{order_id}}

Placeholders are written as {{name}} and are filled from the conversation. They work in the path and the query string only — the host is fixed by you and the chatbot can never change where the request is sent.

5. Configure — authentication. Choose the style your API uses and paste the secret. Once saved, the field shows a "stored" hint and never displays the value again.

6. Configure — parameters. One row per placeholder, so the chatbot knows what to extract:

Name	Type	Required	Description
order_id	string	Yes	The order number the visitor is asking about, exactly as they gave it.

The description is what the model reads when filling the value. "The order number the visitor gave" fills reliably; "id" does not.

7. Test. On the Test tab, type: "where is my order 10482?" You should see that the action would trigger, order_id resolved to 10482, and a request preview pointing at the right address.

8. Enable and try it for real. Turn on Enabled, save, then ask the same thing in Test Chatbot. Open the action's run log and confirm a Success row. See Call Action history.

9. If it needs a body. For an action that creates something, use POST and a JSON body with the same placeholder style:

{
    "email": "{{email}}",
    "subject": "{{subject}}",
    "note": "{{note}}"
}

Values are safely escaped when they are inserted, so a visitor typing a quote mark cannot break the request. Add one parameter row per placeholder, and leave Requires confirmation on.

What you will see

The Actions tab is a card grid with four counters at the top: Actions, Enabled, Total runs, and Success rate. Each card shows the action's type icon, its Enabled or Disabled badge, run count, last run time, and controls for Edit, View logs, Enable / Disable, and Delete.

Creating opens the chooser; picking a type or template opens the slide-over editor. Deleting asks for confirmation and warns that the chatbot will no longer be able to trigger it.

Limits and plan notes

• Enabled actions are what your plan caps: Free 0, Starter 3, Standard 8, Pro 12, Agency 20 per chatbot. Exceeding it returns an upgrade prompt rather than saving. See Plans and what you get.
• Disabled actions are cheap but not free — there is an overall ceiling on how many actions one chatbot may hold in total, enabled or not.
• You need permission to manage actions on that chatbot. See Roles and permissions.
• Saving an action spends nothing. A test run with a sample message makes a real model call, so it needs message credits left to run, but it is not charged as a reply.
• If your chatbot's AI model does not support tool calling, the tab shows "Actions are temporarily unavailable" and nothing will fire. See Chatbot AI settings.
• Within one reply, the chatbot may run several actions but not unlimited ones, and each outbound call has a few seconds to answer.

Common problems

Create is disabled.

Either you are at your plan's enabled-action cap, you lack permission on this chatbot, or Call actions are switched off for this deployment. Check your plan and your role first.

Save fails with a validation message.

The two most common are a description under 8 characters and a URL missing its https:// prefix. The field with the problem is highlighted.

The test says the AI would not trigger this action.

The Test tab now mirrors a real conversation: it retrieves knowledge for your sample sentence (or uses the same no-knowledge prompt a live turn would) and asks the model whether to call this action in addition to answering. If it still would not fire:

• Rewrite When should the AI use this? so it names what the visitor is trying to do, using the words they would type. Weak: Sales invoice. Strong: When the visitor asks how to add or create a sales invoice.
• Re-run with the exact sentence a visitor would send (not a label like the button name alone).
• Check the one-line note on the result card: "Tested with N knowledge passages" vs "Tested with no matching knowledge" tells you which live path was exercised.

A successful Result preview with "would not trigger" still means the connector config is fine — only the model's decision to call it failed.

The test passes but nothing happens in a live chat.

Check in this order: the action is Enabled; the chatbot is active (a paused or draft chatbot answers nothing publicly — see Activate or pause a chatbot); and the visitor's phrasing matches the description. Then open the run log — a run that exists but reads Skipped or Awaiting confirmation tells you exactly which gate you hit.

I pasted a secret and now the field looks empty.

That is correct. Secrets are write-only; the field shows a "stored" hint and leaving it blank on a later edit keeps the stored value. Fill it in only when rotating.

My OpenAPI import only created one action.

The importer walks you through the operations one at a time — save the first and the editor advances to the next. It also needs JSON, not YAML.