Create a Chat Agent via API

Markdown

View as Markdown

Create a Chat Agent via API

This article explains how to create a Chat Agent (chatbot) in your Flora AI account using the REST API. You will learn which endpoint to call, how to authenticate, what parameters are available, and what to expect in the response.

1. Overview

You can create a chatbot programmatically by sending a POST request to the Flora AI Chatbot API. This is useful when you want to:

  • Automate chatbot creation from your own systems or scripts.

  • Create multiple chatbots with different configurations.

  • Integrate chatbot setup into your deployment or onboarding workflows.

2. API Endpoint

Use the following endpoint to create a chatbot:

POST https://app.floraai.me/en/chatbot/api/v1/create-chatbot/

All requests must be sent over HTTPS.

3. Authentication & Headers

Include your API token and content type in the request headers.

Required headers:

Content-Type: application/jsonAuthorization: Token <Your-API-Token>

Optionally, you can also include:

Accept: application/json

Replace <Your-API-Token> with the API token generated from your Flora AI account.

4. Request Body Parameters

Send the request body as JSON. The following fields are available:

Required Fields

  • name (String, Required)
    Internal name of the chatbot. Used to identify the chatbot in your account.

  • base_system_message (String, Required)
    The core instruction or role message given to the LLM (e.g., “You are a helpful support assistant for ACME Inc.”). This strongly influences how the chatbot behaves.

Optional Fields

Display & Branding

  • display_name (String, Optional)
    The name shown to end users in the chat widget. If omitted, the system may fall back to name.

  • support_email (Email, Optional)
    Overrides the default agency support email for this chatbot. This can be shown in the widget or used in notifications.

  • is_pinned (Boolean, Optional)
    If true, the chatbot is pinned to the top of your chatbot list in the dashboard.

Model Configuration

  • chatgpt_model_key (Choice, Optional)
    The primary LLM model key. Example choices include (subject to availability):

  • GPT-3.5

  • GPT-4

  • GPT-4-Turbo

  • GPT_4_TURBO_2024_04_09

  • GPT_4_O_2024_05_13

  • GPT-4o-2024-11-20

  • GPT-4O-mini

  • GPT-4O-2024-08-06

  • GPT-4.1-2025-04-14

  • GPT-4.1-mini-2025-04-14

  • GPT-4.1-nano-2025-04-14

  • GPT-5-2025-08-07

  • GPT-5-mini-2025-08-07

  • GPT-5-nano-2025-08-07

  • GPT-5.2-2025-12-11

  • CLAUDE-3-OPUS-20240229

  • CLAUDE-3-7-sonnet-20250219

  • CLAUDE-3-5-haiku-20241022

  • CLAUDE-SONNET-4-6

  • CLAUDE-HAIKU-4-5-20251001

  • GROK-2-1212

  • GROK-3

  • GROK-3-mini

  • GROK-4-0709

  • GROK-4-1-fast-reasoning

  • GROK-4-1-fast-non-reasoning

  • backup_llm_model_key (Choice, Optional)
    A fallback model key used if the primary model is unavailable. Accepts the same choices as chatgpt_model_key.

  • temperature (Decimal, Optional)
    Controls randomness/creativity of responses.

  • Lower values (e.g., 0.1–0.3) → more deterministic, focused answers.

  • Higher values (e.g., 0.8–1.2) → more creative, varied responses.

Conversation Behavior & Prompts

  • knowledge_base_results_base_system_prompt (String, Optional)
    Additional system prompt used specifically when the chatbot is answering using knowledge base results. Useful for instructing how to use retrieved documents.

  • conversation_starter_message (String, Optional)
    Starter messages shown at the beginning of the conversation.

  • Use newline characters (\n) to separate multiple starter messages.

  • initial_message (String, Optional)
    Initial message(s) the chatbot sends automatically when the chat opens.

  • Also separated by newlines if you want multiple messages.

  • persistent_conversation_starter_message (Boolean, Optional)
    If true, conversation starter messages remain visible throughout the conversation instead of disappearing after the first interaction.

  • llm_driven_conversation_titles (Boolean, Optional)
    If true, the AI automatically generates conversation titles based on the chat context.

Data & Debug Options

  • show_data_sources (Boolean, Optional)
    If true, the chatbot displays data sources (e.g., documents, URLs) used to generate an answer in the widget.

  • debug_mode (Boolean, Optional)
    If true, the chatbot exposes debug information such as matched data from Redisearch for a given query. Useful for troubleshooting relevance and retrieval.

  • top_k (Integer, Optional)
    Number of knowledge base results to fetch and provide as context to the chatbot. Higher values may improve recall but can increase token usage.

  • categories (ManyToMany, Optional)
    A list of category IDs the chatbot belongs to.
    Example: [1, 2, 3]
    Use this to organize chatbots by department, product line, etc.

User Experience Features

  • audio_io_enabled (Boolean, Optional)
    If true, enables audio input/output for the chatbot (voice features, where supported).

  • is_streaming_enabled (Boolean, Optional)
    If true, enables streaming responses so users see the answer as it is generated.

  • image_upload_enabled (Boolean, Optional)
    If true, allows users to upload images/documents for the chatbot to process (where supported by the selected model).

Rate Limiting

These options help control how frequently users can send messages to the chatbot.

  • rate_limiting_enabled (Boolean, Optional)
    If true, enables message rate limiting.

  • time_period (Choice, Optional)
    The time window over which the message limit is enforced. Possible values:

  • per_hour

  • per_day

  • per_month

  • messages_limit (Integer, Optional)
    Maximum number of messages allowed within the selected time_period.

  • cooldown_period (Integer, Optional)
    Cooldown duration in minutes after the user hits the messages_limit. During this period, the user cannot send new messages.

  • cooldown_message (String, Optional)
    Custom message shown to the user when they reach the rate limit (e.g., “You’ve reached the limit for this hour. Please try again later.”).

5. Example Request (Python)

Below is a complete example using Python’s requests library:

import requests# Define the API endpointurl = "https://app.floraai.me/en/chatbot/api/v1/create-chatbot/"# Set up authentication and headersheaders = {    'Authorization': 'Token <YOUR-API-TOKEN>',    'Content-Type': 'application/json',    'Accept': 'application/json'}# Data is passed in the request body as JSONdata = {    "name": "Support Bot - ACME",    "display_name": "ACME Support Assistant",    "chatgpt_model_key": "GPT-4",    "backup_llm_model_key": "GPT-3.5",    "temperature": 0.7,    "support_email": "[email protected]",    "base_system_message": "You are a helpful support assistant for ACME Inc. Answer clearly and concisely.",    "knowledge_base_results_base_system_prompt": "Use the provided documents as the primary source of truth. If unsure, say you don't know.",    "conversation_starter_message": "What can you help me with?\nHow do I track my order?\nWhat is your refund policy?",    "initial_message": "Hi! I'm the ACME Support Assistant.\nHow can I help you today?",    "show_data_sources": True,    "persistent_conversation_starter_message": True,    "debug_mode": False,    "audio_io_enabled": False,    "categories": [1, 2],    "is_streaming_enabled": True,    "top_k": 10,    "image_upload_enabled": True,    "llm_driven_conversation_titles": True,    "rate_limiting_enabled": True,    "time_period": "per_hour",    "messages_limit": 20,    "cooldown_period": 15,    "cooldown_message": "You’ve reached the hourly message limit. Please try again in 15 minutes.",    "is_pinned": True}response = requests.post(url, headers=headers, json=data)# Process the responseif response.status_code in (200, 201, 202):    result = response.json()    print("Response data:", result)else:    try:        error_data = response.json()        error_message = error_data.get('message') or error_data.get('error', 'Unknown error')        print(f"Error: {error_message}")    except ValueError:        print(f"Error: Status code {response.status_code}")

Notes:

  • Ensure temperature is sent as a number (e.g., 0.7), not a string, unless your client library requires otherwise.

  • categories should be a JSON array of integers, not a string representation of a list.

6. Example Response

On success, the API returns a JSON object with a unique identifier for the chatbot and a confirmation message.

{  "uuid": "c39ce12c-01f2-4a7c-bdb0-90a76f8ebe1f",  "message": "Great job! 🚀 Please train your chatbot now to experience the real power of AI!"}

  • uuid: The unique ID of the newly created chatbot. Use this to reference the chatbot in other API calls (e.g., training, updating, or embedding).

  • message: A human-readable confirmation message.

If the request fails (e.g., missing required fields, invalid token), the API returns an error status code and an error message in the response body. Use the error message to adjust your request accordingly.

7. Next Steps

After creating your chatbot:

  1. Use the returned uuid to train the chatbot with your knowledge base or content.

  2. Configure the chat widget or integration where the chatbot will be used.

  3. Test the chatbot’s behavior and adjust parameters such as base_system_message, temperature, and rate limiting as needed.

Was this article helpful?

Still need help?

Contact us

Flora Ai Integrations