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.
| Type | What it does | Compatible channels |
|---|---|---|
| Call API | Calls 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 code | Runs a function you register on your website and returns its result to the bot. | Website channels |
| Call API + show widget | Calls an API and shows the results to the visitor in a card. | Website channels |
| Show widget | Shows 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
-
Open the template. In Bot > Actions, open Action library, select Custom action, and select Start customizing.
-
Complete General. Enter an Action name and a When to use description, then select Continue.
-
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.
-
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.
-
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.
-
Choose channels. Turn on the channels that may use the action, then select Save, or Save & enable.
-
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
| Setting | What it does |
|---|---|
| Action name | The name the bot uses to call this action. Use 3–64 characters. Spaces become underscores. |
| When to use | Tells 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.
| Column | What it does |
|---|---|
| Name | The input’s key, used in the URL, parameters or body. |
| Type | text, number, boolean, email or choice. |
| Description | Tells 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
| Setting | What it does |
|---|---|
| Method | GET, POST, PATCH or DELETE. GET reads data. The others change data and need visitor confirmation. |
| HTTPS URL | A 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:
| Tab | What it does |
|---|---|
| Parameters | Key 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. |
| Headers | Extra 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. |
| Body | For 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:
| Setting | What 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-Key | Confirms 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
| Option | What it does |
|---|---|
| Full data access | The bot can use the whole response, up to 20 KB. |
| Limited data access | The 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.
| Setting | What it does |
|---|---|
| Card title | A short heading visitors see above the values. |
| Card layout | Key/value details, Text blocks, Table or Bar chart with data table. |
| Label as demo data | Labels the card as demo data. Turn it on for mock or example data. |
| Card fields | Show 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 runs | As soon as the bot calls it. | Only after the visitor selects Confirm operation on a Confirm API operation card. |
| What the visitor sees | The 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 limit | 15 seconds. | A confirmation stays active for 10 minutes. |
| Retries | Never 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
Bearerbefore 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.
| Setting | What it does |
|---|---|
| Collect data inputs for action (optional) | Information the bot passes to your function. Leave empty if none is needed. |
| Callback name | The exact name registered with widget.registerTools on your website. It’s separate from the action name. |
| Result fields | The 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
| Type | Chat bubble | Help page | Center stage | API | Fluent Support |
|---|---|---|---|---|---|
Call API with GET | Yes | Yes | Yes | Yes | Yes |
Call API with POST, PATCH or DELETE | Yes | Yes | Yes | No | No |
| Run client-side code | Yes | Yes | Yes | No | No |
| Call API + show widget | Yes | Yes | Yes | No | No |
| Show widget | Yes | Yes | Yes | No | No |
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
/chator pass achat_id. A standalone/responsesrequest 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.