Send Message

Use this API to send messages to a specified conversation_id and receive responses generated by the Agent. The API supports various message content types including text, images, audio, and documents.

Request Method

POST

Endpoint

https://api.gptbots.ai/v2/conversation/message

Authentication

Refer to the authentication instructions in the API Overview.

Request

Request Example

curl -X POST https://api.gptbots.ai/v2/conversation/message \ --header 'Authorization: Bearer app-example_key_1234567890' \ --header 'Content-Type: application/json' \ --data '{ "conversation_id": "67b590ca27008b39c60f30ef", "response_mode": "blocking", "messages": [ { "role": "user", "content": "Hello" }, { "role": "assistant", "content": "Hello! How can I assist you today?" }, { "role": "user", "content": [ { "type": "text", "text": "What is in this image?" }, { "type": "audio", "audio": { "url": "https://gptbots.ai/example.mp3", "name": "example audio", "format": "mp3" } }, { "type": "image", "image": { "url": "https://gptbots.ai/example.png", "format": "png", "name": "example image" } }, { "type": "document", "document": { "base64_content": "Your_file_base64_content", "format": "pdf", "name": "example pdf" } } ] } ], "conversation_config": { "long_term_memory": false, "short_term_memory": false, "knowledge": { "data_ids": [ "58c70da0403cc812641b9356", "59c70da0403cc812641df35k" ], "group_ids": [ "67c70da0403cc812641b93je", "69c70da0403cc812641df35g" ] } } }'

                      
                      curl -X POST https://api.gptbots.ai/v2/conversation/message \
--header 'Authorization: Bearer app-example_key_1234567890' \
--header 'Content-Type: application/json' \
--data '{
    "conversation_id": "67b590ca27008b39c60f30ef",
    "response_mode": "blocking",
    "messages": [
        {
            "role": "user",
            "content": "Hello"
        },
        {
            "role": "assistant",
            "content": "Hello! How can I assist you today?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is in this image?"
                },
                {
                    "type": "audio",
                    "audio": {
                        "url": "https://gptbots.ai/example.mp3",
                        "name": "example audio",
                        "format": "mp3"
                    }
                },
                {
                    "type": "image",
                    "image": {
                        "url": "https://gptbots.ai/example.png",
                        "format": "png",
                        "name": "example image"
                    }
                },
                {
                    "type": "document",
                    "document": {
                        "base64_content": "Your_file_base64_content",
                        "format": "pdf",
                        "name": "example pdf"
                    }
                }
            ]
        }
    ],
    "conversation_config": {
        "long_term_memory": false,
        "short_term_memory": false,
        "knowledge": {
            "data_ids": [
                "58c70da0403cc812641b9356",
                "59c70da0403cc812641df35k"
            ],
            "group_ids": [
                "67c70da0403cc812641b93je",
                "69c70da0403cc812641df35g"
            ]
        }
    }
}'

Este bloque de código en la ventana flotante

Note: For image, audio, and document types, you can use either base64 encoding or URL links - choose one of these two methods.

Request Headers

Field	Type	Description
Authorization	Bearer ${token}	Use Authorization: Bearer ${token} for authentication. Obtain the token from the API Key page.
Content-Type	application/json	Data type, must be application/json.

Request Body

Field	Type	Required	Description
conversation_id	string	Yes	Unique identifier for the conversation. Must provide the conversation_id to continue the conversation.
response_mode	string	Yes	Agent response mode: blocking: Wait until execution finishes and return results (may be interrupted if the process is too long). streaming: Stream response based on SSE (Server-Sent Events). webhook: Messages from Agent and human customer service will be sent to the webhook URL configured on the API page.
messages	JSON Array	Yes	Message content, supports roles `user` and `assistant` to construct conversation context. user message: At least one required, latest user message should be last. assistant message: Developers can construct assistant messages as context.
conversation_config	object	No	Temporarily adjust Agent functionalities for special scenarios. short_term_memory: Enable or disable short-term memory for this conversation. long_term_memory: Enable or disable long-term memory for this conversation. knowledge: Customize knowledge retrieval scope for this conversation. Includes `group_ids` and `data_ids`. If both provided, retrieval occurs within their union. If both empty, no knowledge retrieval occurs. If omitted, default Agent knowledge configuration applies. `group_ids`: Knowledge base ID, which may contain multiple knowledge documents. `data_ids`: Knowledge document IDs in the knowledge base.

Note:

Agent input and output configuration pages support different recognition schemes for different message types. Supported file types and sizes vary. Adjust API submission data accordingly. Maximum supported message formats:

Text message: string

Audio message: .mp3, .wav, .acc

Image message: .jpg, .jpeg, .png, .gif, .webp

Document message: .pdf, .txt, .docx, .csv, .xlsx, .html, .json, .md, .tex, .ts, .xml, etc.

Response

Response Example

{ "create_time": 1679587005, "conversation_id": "657303a8a764d47094874bbe", "message_id": "65a4ccfC7ce58e728d5897e0", "output": [ { "from_component_branch": "1", "from_component_name": "Component Name", "content": { "text": "Hi, is there anything I can help you?", "audio": [ { "audio": "http://gptbots.ai/example.mp3", "transcript": "Transcribed audio content" } ] } } ], "usage": { "tokens": { "total_tokens": 29, "prompt_tokens": 19, "prompt_tokens_details": { "audio_tokens": 0, "text_tokens": 0 }, "completion_tokens": 10, "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "text_tokens": 0 } }, "credits": { "total_credits": 0.0, "text_input_credits": 0.0, "text_output_credits": 0.0, "audio_input_credits": 0.0, "audio_output_credits": 0.0 } } }

                      
                      {
    "create_time": 1679587005,
    "conversation_id": "657303a8a764d47094874bbe",
    "message_id": "65a4ccfC7ce58e728d5897e0",
    "output": [
        {
            "from_component_branch": "1",
            "from_component_name": "Component Name",
            "content": {
                "text": "Hi, is there anything I can help you?",
                "audio": [
                    {
                        "audio": "http://gptbots.ai/example.mp3",
                        "transcript": "Transcribed audio content"
                    }
                ]
            }
        }
    ],
    "usage": {
        "tokens": {
            "total_tokens": 29,
            "prompt_tokens": 19,
            "prompt_tokens_details": {
                "audio_tokens": 0,
                "text_tokens": 0
            },
            "completion_tokens": 10,
            "completion_tokens_details": {
                "reasoning_tokens": 0,
                "audio_tokens": 0,
                "text_tokens": 0
            }
        },
        "credits": {
            "total_credits": 0.0,
            "text_input_credits": 0.0,
            "text_output_credits": 0.0,
            "audio_input_credits": 0.0,
            "audio_output_credits": 0.0
        }
    }
}

Este bloque de código en la ventana flotante

Successful Response (Blocking)

⚠️ Human handoff service is not available in blocking response mode.

Field	Type	Description
conversation_id	string	Yes
message_id	string	Unique identifier for a message within a conversation.
create_time	long	Timestamp when this response message was generated.
output	JSON Array	Agent response content.
from_component_branch	string	FlowAgent branch.
from_component_name	string	Upstream component name in FlowAgent.
content	object	Message content replied by AI Agent, currently includes two types of messages: `text` and `audio`.
usage	object	Resource consumption details.
tokens	JSON Array	Total tokens consumed by the Agent in this conversation.
total_tokens	integer	Total tokens consumed for both input and output in this conversation.
prompt_tokens	integer	Total tokens consumed for input in this conversation.
completion_tokens	integer	Total tokens consumed for output in this conversation.
prompt_tokens_details	object	Detailed token consumption breakdown for input.
completion_tokens_details	object	Detailed token consumption breakdown for output.
credits	object	Total credits consumed by the Agent in this conversation.
text_input_credits	double	Credits consumed for input text messages in this conversation.
text_output_credits	double	Credits consumed for output text messages in this conversation.
audio_input_credits	double	Credits consumed for input audio messages in this conversation.
audio_output_credits	double	Credits consumed for output audio messages in this conversation.

Successful Response (Streaming)

⚠️ Human handoff service is not available in streaming response mode.

Field	Type	Description
code	int	Message type code: 3-Text, 10-FlowAgent output, 0-End, 4-Usage data, 39-Audio message.
message	string	Message type: Text, FlowOutput, End.
data	object	Response content.

Text message streaming example:

{"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}} {"code":3,"message":"Text","data":"How "} {"code":3,"message":"Text","data":"can "} {"code":3,"message":"Text","data":"I "} {"code":3,"message":"Text","data":"help "} {"code":3,"message":"Text","data":"you?"} {"code":0,"message":"End","data":null}

                      
                      {"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}}
{"code":3,"message":"Text","data":"How "}
{"code":3,"message":"Text","data":"can "}
{"code":3,"message":"Text","data":"I "}
{"code":3,"message":"Text","data":"help "}
{"code":3,"message":"Text","data":"you?"}
{"code":0,"message":"End","data":null}

Este bloque de código en la ventana flotante

Audio message streaming example:

{"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}} {"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"Hello"}} {"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}} {"code":0,"message":"End","data":null}

                      
                      {"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"Hello"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":0,"message":"End","data":null}

Este bloque de código en la ventana flotante

Successful Response (Webhook)

⚠️ Human handoff service is available in webhook response mode.
When human customer service is enabled for an Agent, you should use the webhook response mode to receive messages from human customer service representatives. After configuring the webhook URL in the "Integration-API" section, the GPTBots system will send response messages from both the "Agent" and "human customer service" to your webhook URL.

For detailed information about webhook messages, please refer to Webhook Mode and human handoff service.

Error Response

Field	Type	Description
code	int	Error code.
message	string	Error details.

Error Codes

Code	Message
40000	Invalid parameters
40127	Developer authentication failed
40356	Conversation does not exist
40358	Conversation ID mismatch
40364	Agent does not support image modality
50000	Internal system error
20040	Exceeded question length limit
20022	Insufficient credits
20055	API usage forbidden, ensure API switch is enabled