POST AI Support Chatbots API
/api/v1/chatbots
Build customer-facing AI support chatbots with connected knowledge bases, client-managed actions, and automatic conversation context.
Architecture Role & AI Definition
AI Support Chatbots API provides low-latency, deterministic REST execution for production engineering workflows. It processes structured payloads with strict schema validation, returns uniform JSON envelopes, and is secured via SHA-256 API key authentication with atomic credit pre-authorization locks.
Production Reliability Guidelines
Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.
Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).
RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Required | Name of the Chatbot (e.g. "Customer Assistant") |
mode |
string | Optional | Mode: support, faq, sales, or general. Default is support. |
knowledge_base_ids |
array of integers | Optional | Array of linked Knowledge Base IDs for grounded RAG answers. |
description |
string | Optional | Optional description of the assistant role and goals. |
status |
string | Optional | Status: active or inactive. Default is active. |
knowledge_base_id |
integer | Optional | Optional single Knowledge Base ID (older form of knowledge_base_ids; use one or the other). |
settings |
object | Optional | Optional settings object for the chatbot. |
Privacy-First Client-Managed Actions
Your backend credentials and private databases remain 100% private. When a customer query requires a private business action (e.g. get_order_status), the API returns a response of type action_required containing the extracted action parameters. Execute the action inside your own secure infrastructure and submit the result back via POST /api/v1/chatbots/{id}/conversations/{conversation_id}/actions/{action_call_id}/result.
End-to-End Integration Flow
- Create Knowledge Base & Add FAQs/Documents:
POST /api/v1/knowledge-bases - Create Chatbot & Link KB:
POST /api/v1/chatbots - Define Optional Actions:
POST /api/v1/chatbots/{id}/actions - Send Message:
POST /api/v1/chatbots/{id}/messages - Handle Normal Message Response or Action Required Response: If
type == "action_required", execute private action and post result.
Example Message Request
{
"message": "Hi, what is the status of my order ORD-9821?"
}curl -X POST https://rsflowhub.com/api/v1/chatbots/1/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Hi, what is the status of my order ORD-9821?"
}'Example Action Required Response
{
"success": true,
"request_id": "req_7f3a9c2d1e4b8a6f",
"data": {
"type": "action_required",
"conversation_id": "conv_a81f92c3...",
"action_call": {
"id": "action_call_71a2b9...",
"name": "get_order_status",
"arguments": {
"order_id": "ORD-9821"
}
},
"usage": {
"credits_used": 1,
"credits_remaining": 999
}
},
"meta": {
"version": "v1",
"timestamp": "2026-09-27T12:34:56+00:00"
}
}Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 401 | API_KEY_MISSING / INVALID_API_KEY |
No key sent, or the key was mistyped or regenerated. | Copy the current key from Dashboard → API Keys and send it as Authorization: Bearer (or X-API-Key). |
| 402 | INSUFFICIENT_CREDITS |
Your balance cannot cover the estimate for this call (base 4 credits plus input/output size). | Buy a plan in Dashboard → Billing. Nothing was charged. |
| 422 | VALIDATION_ERROR |
A field is missing, too long or the wrong type, or the body is not valid JSON. | Read error.details for the field messages and fix the request. Do not retry the same body. |
| 429 | RATE_LIMIT_EXCEEDED |
Your plan-wide or per-endpoint per-minute limit was reached. | Wait the seconds in the Retry-After header, then retry with jitter. Rate limits |
| 502 | AI_PROVIDER_ERROR |
The AI model and its backup both failed. | Retry with backoff and check the status page. Nothing was charged. |