Skip to content
This site is under construction. Content, screenshots, and workflows may change at any time.

Custom action

A custom action connects your bot to your own systems. It can call an HTTPS API, run a function you register on your website, or show a card in the conversation.

Open Bot > Actions > Action library > Custom action.

Best for: looking up or changing data that lives in your own systems, such as order status, account details or a reservation.

Common requests:

  • “Where is my order 1042?”
  • “Update the delivery address on my order.”
  • “Show me my current plan.”

Action types

When you create a custom action, you choose one of four types in the Action type section.

TypeWhat it doesCompatible channels
Call APICalls an API on the server. No client-side code is needed. With GET, it reads data. With POST, PATCH or DELETE, the visitor confirms the exact request before it runs.GET: all channels. Other methods: website channels
Run client-side codeRuns a function you register on your website and returns its result to the bot.Website channels
Call API + show widgetCalls an API and shows the results to the visitor in a card.Website channels
Show widgetShows a card using details from the conversation. No API runs.Website channels

Website channels are Chat bubble, Help page and Center stage.

After you save a custom action, you can’t change its type or switch between GET and a write method. The editor explains: “To use a different execution type, create another custom action.”

Before you start

  • You need the Owner, Team Admin or Bot Admin role.
  • For Call API types, you need a public HTTPS endpoint that returns JSON. Use a sandbox endpoint while you test.
  • For Run client-side code, your website must load the chat with the JavaScript widget install code, and a developer must register the function. See Run client-side code.

Create a custom action

  1. Open the template. In Bot > Actions, open Action library, select Custom action, and select Start customizing.

  2. Complete General. Enter an Action name and a When to use description, then select Continue.

  3. Choose an action type. In Action type, choose Call API, Run client-side code, Call API + show widget or Show widget. Select Save and continue.

  4. Configure the type. Complete the next section: API, Inputs or Widget. For API types, also complete Test response and Data access, and Widget for Call API + show widget. Select Save and continue on each.

  5. Add the API credential (if used). If you chose an Authentication header, enter its value in API credential and select Save credential, then select Continue to channels.

  6. Choose channels. Turn on the channels that may use the action, then select Save, or Save & enable.

  7. Enable and test. Turn on Enable action. Ask a question in Preview that should trigger the action.

The action is saved when you finish its last configuration section. Until then, the editor says “Your action is saved after its configuration is complete.”

General

SettingWhat it does
Action nameThe name the bot uses to call this action. Use 3–64 characters. Spaces become underscores.
When to useTells the bot when to call this action and what it does. The default for an API read is: “Use this read-only API only for its configured purpose. Ask for missing required inputs. Answer from the returned fields; never invent missing data or claim a write occurred.” Select Reset to restore it.

API

This section appears for Call API and Call API + show widget.

Data inputs

Under Collect data inputs for action (optional), list any information the bot needs to make the request. The bot can find it in the chat history, ask the visitor, or use the visitor’s metadata if available. Select Add data input for each one.

ColumnWhat it does
NameThe input’s key, used in the URL, parameters or body.
Typetext, number, boolean, email or choice.
DescriptionTells the bot what to collect.

Open Labels, choices and validation limits to set labels, choices, required inputs and length limits. You can add up to 20 inputs.

API request

SettingWhat it does
MethodGET, POST, PATCH or DELETE. GET reads data. The others change data and need visitor confirmation.
HTTPS URLA fixed public HTTPS address without a query string, fragment or credentials. Use Add variable to insert an input into the path, such as https://api.example.com/orders/{order_id}. A path variable must be a required input.

Below the URL, three tabs configure the request:

TabWhat it does
ParametersKey and value pairs sent in the URL query for every method. Use fixed values or choose a collected input. For GET, inputs that aren’t used in the path or a parameter are also sent as query keys with their own names.
HeadersExtra request headers. Values are encrypted and kept out of the bot’s configuration. Content-Type and Accept must be application/json. FluentChat manages Idempotency-Key and rejects headers such as Host, Cookie and User-Agent. This tab also holds the Authentication header choice.
BodyFor POST, PATCH and DELETE. Each input becomes a JSON property. Use a path such as /customer/email to nest a value, or open Advanced body mapping.

Authentication header offers No authentication, Authorization, X-API-Key and API-Key. You enter its secret value separately after saving. See Credentials.

Confirmation

For POST, PATCH and DELETE, the Confirmation fields are required:

SettingWhat it does
What will this request change?A short description, up to 200 characters, shown to the visitor before they confirm.
This API honors Idempotency-KeyConfirms your API ignores repeated requests that carry the same Idempotency-Key. FluentChat never retries an uncertain write automatically.

Test response

Choose how to see a sample response:

  • Live response: “Test with live data from the API to make sure it is configured correctly.” Enter Test inputs (JSON) and select Test response. The action configuration and credential must be saved first.
  • Example response: “Use example JSON data if the API is not ready.” Paste a JSON object or array.

Write requests can’t be tested live in the editor. The editor says: “Test this write from Preview after finishing setup and enabling the action.”

Data access

OptionWhat it does
Full data accessThe bot can use the whole response, up to 20 KB.
Limited data accessThe bot only receives the fields you select from the test response, up to 16,000 bytes. Use it to keep sensitive values away from the bot.

The Selected response size meter shows how much of the limit the response uses: 20 KB with Full data access, 16,000 bytes with Limited data access.

Widget

Call API + show widget and Show widget show a card in the chat. Select Edit widget to configure it.

SettingWhat it does
Card titleA short heading visitors see above the values.
Card layoutKey/value details, Text blocks, Table or Bar chart with data table.
Label as demo dataLabels the card as demo data. Turn it on for mock or example data.
Card fieldsShow widget only. The typed values the bot fills in from the conversation.

A Show widget card is labeled Chatbot-provided, because its values come from the conversation, not from a verified API result.

Read and write requests

GET (read)POST, PATCH, DELETE (write)
When it runsAs soon as the bot calls it.Only after the visitor selects Confirm operation on a Confirm API operation card.
What the visitor seesThe bot’s answer, or a result card for Call API + show widget.The method, destination, your description and the exact values before anything is sent.
Time limit15 seconds.A confirmation stays active for 10 minutes.
RetriesNever retried automatically.Never retried automatically. Each request carries an Idempotency-Key.

A write counts as successful when your API returns 200 or 201 with a valid response, or 204 when no response fields are configured. A 202 response, an error or a timeout leaves the outcome uncertain, because your API might already have made the change. The visitor sees Check status instead of a retry.

The visitor can select Cancel instead. The card then says “Operation cancelled. No request was sent.”

Credentials

  • Never put credentials in the URL or in When to use. Use the Authentication header and the API credential section.
  • The value is write-only. After you select Save credential, the editor shows “A credential is saved. Its value is never shown again.” Select Remove credential to delete it.
  • Bearer tokens need the prefix. For bearer authentication, include Bearer before the token.
  • Changing the endpoint or header clears the credential and disables the action. Save a new value, then enable the action again.
  • Credentials and header values are never sent to the bot.

Run client-side code

Run client-side code calls a function on the page where the chat is installed and waits for its result.

SettingWhat it does
Collect data inputs for action (optional)Information the bot passes to your function. Leave empty if none is needed.
Callback nameThe exact name registered with widget.registerTools on your website. It’s separate from the action name.
Result fieldsThe structured result your function returns. Add 1–20 fields. Only configured fields are accepted.

Ask your developer to register the callback after the widget mounts. In the install code from Add to website, add the registration inside the .then() callback, where the widget handle is available. Don’t mount a second widget.

window.FluentChat.mount({ botId: "YOUR_BOT_ID" }).then((widget) => {
window.fluentChatWidget = widget;
widget.registerTools({
check_order_status: async (inputs, { signal }) => {
const response = await fetch(
`/api/orders/${encodeURIComponent(inputs.order_id)}`,
{ signal },
);
if (!response.ok) throw new Error("Order lookup failed");
const order = await response.json();
// Return only the configured result fields.
return { status: order.status };
},
});
// Lists registered callbacks. It doesn't run them.
console.table(widget.getActionReadiness());
});

The function has up to 30 seconds to return a result. Missing callbacks and failed or late results are reported as unsuccessful, and the bot doesn’t claim the action worked. For operations that change customer data, check permissions on your server. See Widget SDK for the full widget API.

Channel compatibility

TypeChat bubbleHelp pageCenter stageAPIFluent Support
Call API with GETYesYesYesYesYes
Call API with POST, PATCH or DELETEYesYesYesNoNo
Run client-side codeYesYesYesNoNo
Call API + show widgetYesYesYesNoNo
Show widgetYesYesYesNoNo

Limitations

  • Inputs are single values. Custom API inputs can’t be arrays; the editor says “Array inputs are not supported by custom API actions yet.”
  • API actions need a conversation. On the API channel, start with /chat or pass a chat_id. A standalone /responses request without a conversation can’t use them. See API channel.
  • Responses must be JSON. The bot reads up to 20 KB with Full data access.
  • No redirects or dynamic hosts. The endpoint’s host is fixed; only path variables, parameters and body values change.
  • Writes can’t be tested in the editor. Test them in Preview after enabling, against a sandbox.
  • Client-side code needs the JavaScript widget. The iframe embed can’t register callbacks.

Troubleshooting

Save the API credential before enabling this action.

Possible cause: The action uses an Authentication header, but no value is saved.

Solution: Open the action, enter the value in API credential, and select Save credential.

Use a fixed HTTPS endpoint without query parameters, fragments or credentials.

Possible cause: The URL uses http, includes ? parameters or #, or contains a username or password.

Solution: Use an https address and move query values to Parameters.

The action was enabled but is now disabled

Possible cause: You changed the URL or the authentication header, which clears the credential and disables the action.

Solution: Save the credential again and turn on Enable action.

The client-side action always fails

Possible cause: The Callback name doesn’t match the name passed to widget.registerTools, or the function was registered before the widget mounted.

Solution: Run console.table(widget.getActionReadiness()) in the browser console and check that the callback name is listed.

Next steps