API channel
The API channel is how your own application talks to the bot over the REST API. The /chat and /responses endpoints share this channel, so they use the same availability, instructions, and action permissions.
Open Bot > Channels > API. The page shows Instructions, Actions, Make your first request, and Browser and mobile apps, with Manage API keys in the header.
This page covers channel configuration. For request and response formats, see REST API.
Before you start
- You need API key access to open the API channel and turn it on: Owner, Team Admin, or Bot Admin. Other roles see “Team API key access is needed to manage keys.”
- You need a team API key from Settings > API Keys that can access this bot. See API keys.
- Changing instructions or action permissions needs bot edit access: Owner, Team Admin, or Bot Admin.
Make your first request
-
Turn the channel on. In Bot > Channels, turn on the API availability switch. The API channel starts Disabled on a new bot.
-
Create a team API key. Select Manage API keys, then create a key with access to this bot. New keys have Send chat messages and Request responses selected.
-
Store the key on your server. Set it as
FLUENTCHAT_API_KEYin your server environment. Never put it in browser or mobile app code. -
Copy the example. Under Make your first request, choose /responses or /chat, then select Copy example and run it.
The /responses example looks like this. The copied example includes your bot ID.
curl "https://dash.fluentbot.ai/api/responses" \-H "Authorization: Bearer $FLUENTCHAT_API_KEY" \-H "Content-Type: application/json" \-H "Accept: application/json" \--data '{"bot_id": "YOUR_BOT_ID","message": "How can you help me?","stream": false}'Choose an endpoint
| Endpoint | What it does |
|---|---|
/responses | ”Send a standalone message and receive an answer. Without a chat_id, this endpoint does not create a conversation.” The message goes in message. |
/chat | ”Send a prompt to create a conversation. The response includes a chat_id you can reuse.” The message goes in prompt. |
To continue a conversation, start with /chat to get a chat_id, then pass that ID to either endpoint. A standalone /responses request doesn’t return a new conversation ID.
| Topic | What the app says |
|---|---|
| Authentication | ”Use a Bearer token or the X-Api-Key header. Keep the key on your server.” |
| Streaming | ”Set stream: true to receive server-sent events. The example uses a single JSON response.” |
Instructions
The Instructions section works like every other channel. With Use global instructions on, API answers follow the bot’s global instructions. Turn it off to write API-only instructions. See Instructions.
Requests can’t override these instructions. A request that includes system_prompt is rejected with “Instructions are configured on the bot channel, not this request.”
Actions
The Actions section sets which configured actions API requests can use. “Knowledge search is always available. Choose which configured actions this channel can use.”
Only actions that work without a website visitor appear here: Web search, FluentCart, and custom actions that read from an API. Website-only actions, such as live chat, forms, and buttons, don’t apply.
“Both endpoints use the API channel’s permissions. Website action permissions apply only to website sessions.”
Browser and mobile apps
To let a browser or mobile app chat directly, your server issues it a short-lived session token instead of sharing the API key.
-
Allow session issuing on a key. In Settings > API Keys, select Issue browser and mobile sessions on the key your server uses. “Sessions cannot exceed this key’s permissions or the API channel’s allowed actions.”
-
Request a session from your server. Send
POST /api/channels/api/sessionswith the bot ID, asubjectfrom your signed-in user, theoperationsthe session may use, and anaction_ceiling. -
Return the token to your app. The app calls
/chatwithAuthorization: Bearer <session token>. Each token works for 15 minutes.
{ "bot_id": "YOUR_BOT_ID", "subject": "user_123", "operations": ["chat", "history"], "action_ceiling": []}An empty action_ceiling allows knowledge answers with no actions. “Add permitted action keys to action_ceiling when issuing a session. Actions must also be enabled for this API channel.”
Allowed operations are chat, responses, history, stream, and feedback. A session can’t use an operation its parent key doesn’t have.
Limitations
- Session tokens expire after 15 minutes. Request a new one from your server when it expires.
- A session can’t exceed its parent key. Its operations and actions are limited by the key’s permissions and the API channel’s allowed actions.
- Requests can’t change instructions or actions. Configure them on this channel instead.
- Website-only actions aren’t available. Live chat, forms, buttons, and similar actions work only on website channels.
Troubleshooting
This channel is disabled.
Possible cause: The API channel is turned off.
Solution: In Bot > Channels, turn on API availability.
stream_forbidden
Possible cause: The request asks for a streamed answer, but the key doesn’t have Stream conversation events. Requests stream unless they set "stream": false.
Solution: Set "stream": false, or use a key that has Stream conversation events selected in Settings > API Keys.
bot_forbidden or operation_forbidden
Possible cause: The key can’t access this bot, or it lacks the permission for this endpoint.
Solution: Use a key from Settings > API Keys whose Bot access includes this bot and that has the permission you need, such as Send chat messages for /chat or Request responses for /responses.
Instructions are configured on the bot channel, not this request.
Possible cause: The request includes system_prompt.
Solution: Remove system_prompt and set instructions in the API channel’s Instructions section.