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-${endpoint}.gptbots.ai/v2/conversation/message

Authentication

Refer to API Overview for authentication instructions.

Request

Request Example

curl -X POST 'https://api-${endpoint}.gptbots.ai/v2/conversation/message' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "conversation_id": "686e2646cb8ee942d9a62d79", "response_mode": "blocking", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "I have uploaded 2 image files, please OCR and return 2 json records." }, { "type": "image", "image": [ { "base64_content": "<complete_base64_string>", "format": "jpeg", "name": "TAXI1" }, { "url": "https://gptbots.ai/example.png", "format": "png", "name": "TAXI2" } ] }, { "type": "audio", "audio": [ { "url": "https://gptbots.ai/example.mp3", "format": "mp3", "name": "example1 audio" } ] }, { "type": "document", "document": [ { "base64_content": "<complete_base64_string>", "format": "pdf", "name": "example pdf" } ] } ] } ], "conversation_config": { "long_term_memory": false, "short_term_memory": false, "knowledge": { "data_ids": [ "58c70da0403cc812641b9356", "59c70da0403cc812641df35a" ], "group_ids": [ "67c70da0403cc812641b93je", "69c70da0403cc812641df35f" ] }, "custom_variables": { "var_current_url": "https://gptbots.ai/example", "var_session_id": "abcdef" } } }'

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v2/conversation/message' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "conversation_id": "686e2646cb8ee942d9a62d79",
    "response_mode": "blocking",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "I have uploaded 2 image files, please OCR and return 2 json records."
                },
                {
                    "type": "image",
                    "image": [
                        {
                            "base64_content": "<complete_base64_string>",
                            "format": "jpeg",
                            "name": "TAXI1"
                        },
                        {
                            "url": "https://gptbots.ai/example.png",
                            "format": "png",
                            "name": "TAXI2"
                        }
                    ]
                },
                {
                    "type": "audio",
                    "audio": [
                        {
                            "url": "https://gptbots.ai/example.mp3",
                            "format": "mp3",
                            "name": "example1 audio"
                        }
                    ]
                },
                {
                    "type": "document",
                    "document": [
                        {
                            "base64_content": "<complete_base64_string>",
                            "format": "pdf",
                            "name": "example pdf"
                        }
                    ]
                }
            ]
        }
    ],
    "conversation_config": {
        "long_term_memory": false,
        "short_term_memory": false,
        "knowledge": {
            "data_ids": [
                "58c70da0403cc812641b9356",
                "59c70da0403cc812641df35a"
            ],
            "group_ids": [
                "67c70da0403cc812641b93je",
                "69c70da0403cc812641df35f"
            ]
        },
        "custom_variables": {
            "var_current_url": "https://gptbots.ai/example",
            "var_session_id": "abcdef"
        }
    }
}'

Este bloque de código en una ventana flotante

Important Notes:

For image, audio, and document content types, you can use either base64 encoding or URL links - both formats are supported.

Developers only need to send the latest user message, as GPTBots handles short-term and long-term memory by default. If you need to customize the short-term memory context, refer to the example below:

"messages": [ { "role": "user", "content": "Hello" //Custom short-term memory }, { "role": "assistant", "content": "Hello! How can I assist you today?" //Custom short-term memory }, { "role": "user", "content": "Hello" //Latest user message }]

                      
                          "messages": [
        {
            "role": "user", 
            "content": "Hello"                                //Custom short-term memory
        },
        {
            "role": "assistant",
            "content": "Hello! How can I assist you today?"   //Custom short-term memory
        },
        {
            "role": "user",
            "content": "Hello"                                //Latest user message
        }]

Este bloque de código en una ventana flotante

Request Headers

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

Request Parameters

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	Allows developers to temporarily adjust the Agent's functional scope for this conversation to meet special requirements.
short_term_memory	boolean	No	Short-term memory switch. Enable or disable short-term memory for this conversation only.
long_term_memory	boolean	No	Long-term memory switch. Enable or disable long-term memory for this conversation only.
knowledge	object	No	Knowledge retrieval scope. Customize the knowledge retrieval range for this conversation only. When both `group_ids` and `data_ids` are provided, retrieval is performed within the union of their knowledge bases. If both are empty arrays, no knowledge is retrieved. If the `knowledge` parameter is omitted, the Agent's default knowledge configuration is used. `group_ids`: Knowledge base IDs, which may contain multiple knowledge documents. `data_ids`: Knowledge document IDs within the knowledge base.
custom_variables	object	No	Custom variables. Allows developers to temporarily adjust the values of custom variables in the Agent for this conversation only.

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 una 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 una 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 una 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