April logoApril
Sign Up

Custom Actions

Connect your own API so your agent can take custom actions - look things up and make changes in your systems during a chat.

A Custom Action lets your agent call your own API in the middle of a conversation — to look something up or make a change in your systems and answer with the real result. Instead of only quoting your help docs, your agent can fetch a live order status, check stock, create a ticket, or update a record, then reply with what it actually found.

You build a Custom Action in the Actions editor as a series of short steps: name it, describe the request, test it, decide how much of the response the agent can read, and turn it on. April collects the inputs the agent needs, fills them into your request, calls your endpoint, and hands the result back to the agent to use in its reply.

Setup

Open your chatbot, go to Actions in the sidebar, and click New action to open the editor. The editor walks top to bottom — each step shows a check once it's complete.

Step 1: General

Name the action and tell the agent when to use it.

  1. Name — a short, lowercase snake_case identifier, e.g. get_order_status. This is how the agent refers to the action internally.
  2. When to use — a plain-language description of the situations the agent should reach for this action, e.g. "Use this when a visitor asks about the status of an order." The agent decides whether to call the action based on what you write here, so be specific.
  3. Action type — choose how the action runs (see Action types below).

Step 2: API

This step appears for the Server and Server + widget types. Here you configure the exact HTTP request April makes when the agent calls the action.

  1. Method — the HTTP method: GET, POST, PUT, PATCH, or DELETE.

  2. Endpoint URL — your API endpoint. It must be a secure HTTPS URL, e.g. https://api.example.com/orders.

  3. Inputs — the data-inputs table where you define the values the agent collects from the conversation and fills into the request. Each row has:

    • Name — the field name (e.g. order_id).
    • Type — string, number, boolean, or object.
    • Description — what the value is, so the agent knows what to collect (e.g. "The order's ID").
    • Array — check this if the input is a list of values rather than a single one.
    • Required — check this if the agent must have the value before calling the action.

    Click Add variable to add a row. For schemas the table can't express (nested objects, enums, and so on), use Edit as JSON to write the input schema directly.

  4. Request — three tabs that shape the outgoing request, each badged with how many entries it holds:

    • Parameters — key/value pairs appended to the URL as query-string parameters.
    • Headers — request headers, such as an Authorization header for your API key.
    • Body — a JSON request body. Leave it empty to send the inputs as the body automatically.

Inside any URL, parameter value, header value, or body field you can use {{variable}} templating to insert an input the agent collected. See Templating below.

Step 3: Test response

Run the request once so you can confirm it works and capture the shape of the response the agent will see.

  1. Sample inputs — edit the example values for your inputs (pre-filled from your input definitions). These are used only for this test call.
  2. Click Send test request to call your endpoint live and capture the JSON it returns.
  3. Or, if you'd rather not call the live endpoint yet, paste a representative response under or paste an example and click Use example.

The Captured response is saved with the action. It's what powers the next step's field picker.

Step 4: Data access

Control how much of the response the agent is allowed to read.

  • Full — the agent can read the entire response.
  • Limited — only the fields you list are exposed to the agent. After you've captured a response in the previous step, pick the allowed fields by checkbox; otherwise enter them as a comma-separated list (e.g. status, tracking_number, eta).

Use Limited whenever your endpoint returns more than the agent needs — internal IDs, pricing, customer PII — so none of it can leak into a reply.

Step 5: Enable

Toggle Enabled on. While it's on, the agent may call this action during conversations. Click Save action to finish.

Test it in the Playground before you ship: ask the kind of question your "When to use" description covers and watch the agent collect the inputs, call your endpoint, and answer with the result.

Action types

There are four types, chosen in the General step:

  • Server — the agent calls your external API and summarizes the result in its reply. Best for lookups and changes where a written answer is enough ("Your order shipped and arrives Jun 9").
  • Server + widget — the agent calls your API and shows the result inside a widget — a small interactive card in the chat — instead of (or alongside) plain text. Requires a saved widget to attach.
  • Widget only — shows a widget populated with values the agent provides, with no API call at all. Useful for forms, choices, or summaries the agent assembles itself.
  • Client — runs entirely in the visitor's browser with no external call. Reserved for browser-only behaviors.

For Server + widget and Widget only, attach a Widget in the General step. If you haven't built one yet, create it under Widgets first, then come back and attach it here.

Templating

Anywhere in the request, wrap an input name in double curly braces to insert the value the agent collected: {{order_id}}. Templating works in the Endpoint URL, in Parameters and Headers values, and inside the Body.

{
  "id": "{{order_id}}",
  "include_tracking": true
}

A few defaults make simple actions effortless:

  • If you leave the Body empty on a POST/PUT/PATCH, April sends the collected inputs as the JSON body automatically.
  • If you leave Parameters empty on a GET, April appends the collected inputs to the URL as query parameters automatically.

Every request runs over HTTPS only, with a timeout and a response-size cap, so a slow or oversized endpoint can't hang a conversation.

Functions on widget buttons

When an action returns a widget, the buttons inside it can run their own logic — your agent's reply becomes interactive, not just informative. For each button you can configure:

  • Additional Inputs — collect a field or two right on the card before the button runs (for example, a reason or a quantity), so the visitor fills them in place instead of typing a follow-up message.
  • A loading spinner — show a spinner on the button while the request is in flight, so the visitor knows something is happening.
  • Follow-up Actions — chain a next step. When the button's action succeeds, April folds a short instruction into the result so the agent continues automatically — running the action you name and/or doing what the instruction says — instead of stopping. This is how you turn a lookup into a flow: look up the order → offer a "Start return" button → create the return → confirm.

Example Conversation

Here's an "order status" lookup built as a Server action: method GET, endpoint https://api.example.com/orders/{{order_id}}, one required string input named order_id, an Authorization header carrying the API key, and Limited data access exposing only status, eta, and tracking_number.

Visitor: Hi, where's my order? It's order 48213.

Agent: Let me check that for you.

Agent: Good news — order 48213 has shipped and is expected to arrive Jun 9. Your tracking number is 1Z999AA10123456784. Anything else I can help with?

Visitor: Actually, can I return one of the items?

Agent: Of course — I've started a return for order 48213. What's the reason for the return?

Behind the scenes the agent collected order_id, called your endpoint, read only the three allowed fields, and answered. The "Start return" follow-up then chained into a second action to open the return.

FAQ

What does my endpoint need to return? JSON works best — April parses the response and hands the relevant fields to the agent. Plain text is accepted too, but structured JSON lets you control exactly which fields the agent sees with Limited data access.

How does the agent know which inputs to collect? From your input definitions. The Name, Type, and Description of each input tell the agent what to ask for, and Required inputs are gathered before the action runs.

Can the agent change data, not just read it? Yes. Use POST, PUT, PATCH, or DELETE to create or update records — open a ticket, create a deal, update a subscription. The same input collection and templating apply.

How do I send my API key? Add it as a header in the Headers tab, for example an Authorization header with a value like Bearer {{token}}, or a fixed key value. Headers are sent only to your endpoint.

My API response doesn't match what I want the agent to see — what now? Switch Data access to Limited and pick only the fields the agent should read. Everything else in the response is dropped before it reaches the agent.

Does the action have to call an external API? No. Widget only actions show a widget from values the agent provides, and Client actions run in the browser — neither makes an outbound call. Only Server and Server + widget call your endpoint.

Can one action lead to another? Yes — use Follow-up Actions on a returned widget's button to chain the next step, so a lookup can flow straight into an update without the visitor having to ask again.