Send a Message to Chat Agent

Markdown

View as Markdown

Send a Message to Chat Agent (API Guide)

This article explains how to send a message to a chat agent using the Flora AI Chatbot Message API. You will learn how to construct the request, include optional parameters like attachments, and handle responses and errors.

Overview

You can interact with the chat agent by sending a POST request to the Message API. This allows you to:

  • Send user messages (queries)

  • Receive AI-generated replies

  • Attach files (images/documents)

  • Configure custom system prompts

  • Set up human handoff callbacks

API Endpoint

Use the following endpoint to send a message:

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

Required Request Headers

Include these headers in every request:

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

  • Content-Type: application/json
    Indicates that the request body is JSON.

  • Authorization: Token <Your-API-Token>
    Replace <Your-API-Token> with your actual API token.

You may also include:

Accept: application/json

to explicitly request a JSON response.

Request Body Parameters

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

1. chatbot_uuid (UUID, Required)

  • Description: Unique identifier of the chatbot you want to interact with.

  • Where to find: On the chatbot’s detail page in your Flora AI dashboard.

  • Example: "12345678-1234-5678-1234-567812345678"

2. query (String, Required)

  • Description: The message or question you want to send to the chatbot.

  • Constraints: Must be under 5000 characters.

  • Example: "What are your support hours?"

3. user_key (String, Required)

  • Description: A unique identifier for the end user.
    This is used to distinguish different users and maintain conversation context.

  • Example: "user_12345" or "[email protected]"

4. recipent_url (URL, Optional)

  • Description: A callback URL used for human handoff.
    When a conversation is handed off to a human agent, messages from the human will be sent to this URL.

  • Example: "https://example.com/support/handoff"

5. custom_base_system_prompt (String, Optional)

  • Description: A custom system message that overrides the chatbot’s default base system prompt for this request.

  • Use case: Temporarily change the chatbot’s behavior or instructions without editing the chatbot configuration.

  • Example: "You are a friendly customer support assistant for ACME Corp."

6. chat_files (List[Dict], Optional)

  • Description: A list of attachments to send with the message.

  • Each item must include:

  • content: Base64-encoded file content with a data URI prefix
    (e.g., "data:image/png;base64,...")

  • filename: The file name, including extension (e.g., "screenshot.png")

  • Supported file types:

  • Images: JPG, PNG, GIF, WEBP

  • Documents: PDF, TXT, DOCX, XLSX, CSV

  • Limits:

  • Maximum 10 images

  • Maximum 5 documents

  • Maximum size 10 MB per file

  • Example item:

  {    "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...",    "filename": "screenshot.png"  }

Full Request Example (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/message/"# 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 = {    "chatbot_uuid": "12345678-1234-5678-1234-567812345678",    "query": "Your message/string here.",    "user_key": "unique_user_identifier_here",    "recipent_url": "https://example.com",    "custom_base_system_prompt": "Your message/string here.",    "chat_files": None}# Add files/images (optional)data["chat_files"] = [    {        "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...",        "filename": "screenshot.png"    },    {        "content": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MK...",        "filename": "document.pdf"    }]# Send the POST requestresponse = 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}")

Key points:

  • Replace <YOUR-API-TOKEN> with your actual token.

  • Ensure chatbot_uuid, query, and user_key are correctly set.

  • Set chat_files to None or omit it if you are not sending attachments.

Successful Response Example

On success, the API returns a JSON object with a message and data:

{    "message": "Chat Agent successfully answered.",    "data": {        "answer": "If you have a specific question or need assistance with something, please let me know and I`ll be happy to help.",        "chat_id": 634    }}

  • message: A human-readable status message.

  • data.answer: The chatbot’s reply to your query.

  • data.chat_id: The internal ID of the chat session.
    You can use this to track or reference the conversation.

Error Handling

Always check the HTTP status code and handle non-2xx responses.

Missing Authentication Token

If no token is provided or it is invalid, you may receive:

{    "detail": "Authentication credentials were not provided."}

Action:
Ensure the Authorization header is present and correctly formatted:

Authorization: Token <Your-API-Token>

Invalid or Missing Parameters

If required parameters are missing or invalid, you may receive:

{    "message": "The provided parameters are not valid. Please check and try again.",    "errors": {        "chatbot_uuid": [            "This field is required."        ]    }}

Action:

  • Review the errors object to see which fields are problematic.

  • Ensure all required fields (chatbot_uuid, query, user_key) are included and correctly formatted.

  • Correct the request and try again.

General Error Handling Pattern

When the status code is not 200/201/202:

  1. Attempt to parse the JSON response.

  2. Look for message, error, or detail fields.

  3. Log or display the error for debugging.

Handoff Data Payload (Human Handoff)

When a conversation is handed off to a human agent, messages from the human will be sent to the recipent_url you provided. The payload will have the following structure:

{    "chat_id": 1092,    "user_key": "user_key",    "chatbot_uuid": "1367423e-521c-425b-8d5d-32eee36d8f8e",    "message": "Hello How can I assist you today?",    "conversation_id": 310}

Field descriptions:

  • chat_id: The ID of the chat session.

  • user_key: The same user identifier you provided in the original request.

  • chatbot_uuid: The chatbot’s UUID.

  • message: The message sent by the human agent.

  • conversation_id: The ID of the conversation thread.

Use this payload in your backend to:

  • Display messages to your support agents or internal tools.

  • Log or store conversation history.

  • Implement custom workflows when a human joins the conversation.

Summary

To send a message to the chat agent:

  1. Prepare a POST request to
    https://app.floraai.me/en/chatbot/api/v1/message/

  2. Include the required headers:

  • Content-Type: application/json

  • Authorization: Token <Your-API-Token>

  1. Provide at least chatbot_uuid, query, and user_key in the JSON body.

  2. Optionally include recipent_url, custom_base_system_prompt, and chat_files.

  3. Handle both success and error responses based on the HTTP status code and returned JSON.

Was this article helpful?

Still need help?

Contact us

Flora Ai Integrations