Enviar mensaje

Se utiliza esta API para enviar mensajes a un conversation_id especificado y recibir respuestas generadas por el agente. La API admite varios tipos de contenido de mensaje, incluidos texto, imágenes, audio y documentos.

Método de solicitud

POST

Endpoint

https://api-${endpoint}.gptbots.ai/v2/conversation/message

Autenticación

Para obtener instrucciones de autenticación, consulte API Overview (Visión general).

Solicitud

Ejemplo de solicitud

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

Notas importantes:

Para los tipos de contenido image, audio y document, se puede utilizar codificación base64 o enlaces URL; ambos formatos son compatibles.

Los desarrolladores solo deben enviar el mensaje de usuario más reciente, ya que GPTBots gestiona de forma predeterminada la memoria a corto y largo plazo. Si se necesita personalizar el contexto de memoria a corto plazo, consulte el siguiente ejemplo:

"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

Cabeceras de la solicitud

Campo	Tipo	Descripción
Authorization	Bearer ${API Key}	Se utiliza `Authorization: Bearer ${API Key}` para la autenticación. La clave de API se obtiene en la página «API Key».
Content-Type	application/json	Tipo de datos; debe ser `application/json`.

Parámetros de la solicitud

Campo	Tipo	Obligatorio	Descripción
conversation_id	string	Sí	Identificador único de la conversación. Se debe proporcionar `conversation_id` para continuar la conversación.
response_mode	string	Sí	Modo de respuesta del agente: blocking: Se espera a que finalice la ejecución y se devuelven los resultados (puede interrumpirse si el proceso es demasiado largo). streaming: Se transmite la respuesta mediante SSE (Server-Sent Events). webhook: Los mensajes del agente y del servicio de atención al cliente humano se enviarán a la URL del webhook configurada en la página de la API.
messages	matriz JSON	Sí	Contenido del mensaje; admite los roles `user` y `assistant` para construir el contexto de la conversación. mensaje de usuario: Se requiere al menos uno; el mensaje de usuario más reciente debe ser el último. mensaje de asistente: Los desarrolladores pueden construir mensajes del asistente como contexto.
conversation_config	object	No	Permite a los desarrolladores ajustar temporalmente el ámbito funcional del agente para esta conversación a fin de cumplir requisitos especiales.
short_term_memory	boolean	No	Conmutador de memoria a corto plazo. Permite habilitar o deshabilitar la memoria a corto plazo solo para esta conversación.
long_term_memory	boolean	No	Conmutador de memoria a largo plazo. Permite habilitar o deshabilitar la memoria a largo plazo solo para esta conversación.
knowledge	object	No	Ámbito de recuperación de conocimiento. Permite personalizar el rango de recuperación de conocimiento solo para esta conversación. Cuando se proporcionan `group_ids` y `data_ids`, la recuperación se realiza dentro de la unión de sus bases de conocimiento. Si ambos son matrices vacías, no se recupera ningún conocimiento. Si se omite el parámetro `knowledge`, se utiliza la configuración de conocimiento predeterminada del agente. `group_ids`: ID de base de conocimiento, que pueden contener varios documentos de conocimiento. `data_ids`: ID de los documentos de conocimiento dentro de la base de conocimiento.
custom_variables	object	No	Variables personalizadas. Permite a los desarrolladores ajustar temporalmente los valores de las variables personalizadas en el agente solo para esta conversación.
thinking	boolean	No	Controla si se devuelve información de Thinking en streaming.
tool_call	boolean	No	Controla si se devuelve información de llamada a herramientas en streaming.

Nota:

Las páginas de configuración de entrada y salida del agente admiten diferentes esquemas de reconocimiento para distintos tipos de mensajes. Los tipos y tamaños de archivo admitidos varían. Se deben ajustar los datos enviados a la API en consecuencia. Formatos de mensaje máximos admitidos:

Mensaje de texto: string

Mensaje de audio: .mp3, .wav, .acc

Mensaje de imagen: .jpg, .jpeg, .png, .gif, .webp

Mensaje de documento: .pdf, .txt, .docx, .csv, .xlsx, .html, .json, .md, .tex, .ts, .xml, etc.

Respuesta

Ejemplo de respuesta

{ "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

Respuesta correcta (Blocking)

⚠️ El servicio de transferencia a un agente humano no está disponible en el modo de respuesta blocking.

Campo	Tipo	Descripción
conversation_id	string	Identificador de la conversación; se debe proporcionar `conversation_id` para continuar la conversación.
message_id	string	Identificador único de un mensaje dentro de una conversación.
create_time	long	Marca de tiempo de cuando se generó este mensaje de respuesta.
output	matriz JSON	Contenido de la respuesta del agente.
from_component_branch	string	Rama de FlowAgent.
from_component_name	string	Nombre del componente ascendente en FlowAgent.
content	object	Contenido del mensaje respondido por el agente de IA; actualmente incluye dos tipos de mensajes: `text` y `audio`.
usage	object	Detalles del consumo de recursos.
tokens	matriz JSON	Total de tokens consumidos por el agente en esta conversación.
total_tokens	integer	Total de tokens consumidos, tanto de entrada como de salida, en esta conversación.
prompt_tokens	integer	Total de tokens consumidos para la entrada en esta conversación.
completion_tokens	integer	Total de tokens consumidos para la salida en esta conversación.
prompt_tokens_details	object	Desglose detallado del consumo de tokens de entrada.
completion_tokens_details	object	Desglose detallado del consumo de tokens de salida.
credits	object	Total de créditos consumidos por el agente en esta conversación.
text_input_credits	double	Créditos consumidos por mensajes de texto de entrada en esta conversación.
text_output_credits	double	Créditos consumidos por mensajes de texto de salida en esta conversación.
audio_input_credits	double	Créditos consumidos por mensajes de audio de entrada en esta conversación.
audio_output_credits	double	Créditos consumidos por mensajes de audio de salida en esta conversación.

Respuesta correcta (Streaming)

⚠️ El servicio de transferencia a un agente humano no está disponible en el modo de respuesta streaming.

Campo	Tipo	Descripción
code	int	Código del tipo de mensaje: 3-Text, 10-FlowAgent output, 0-End, 4-Usage data, 39-Audio message, 5-Tool Call Request, 6-Tool Call Response, 41-Thinking.
message	string	Tipo de mensaje: Text, FlowOutput, End.
data	object	Contenido de la respuesta.

Ejemplo de transmisión de mensaje de texto:

{"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

Ejemplo de transmisión de mensaje de audio:

{"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

Respuesta correcta (Webhook)

⚠️ El servicio de transferencia a un agente humano está disponible en el modo de respuesta webhook.
Cuando se habilita el servicio de atención al cliente humano para un agente, se debe utilizar el modo de respuesta webhook para recibir mensajes de los representantes de atención al cliente humanos. Tras configurar la URL del webhook en la sección «Integration-API», el sistema GPTBots enviará mensajes de respuesta tanto del «Agent» como del «human customer service» a su URL de webhook.

Para obtener información detallada sobre los mensajes del webhook, consulte Modo webhook y servicio de transferencia a un agente humano.

Respuesta de error

Campo	Tipo	Descripción
code	int	Código de error.
message	string	Detalles del error.

Códigos de error

Código	Mensaje
40000	Parámetros no válidos
40127	Error de autenticación del desarrollador
40356	La conversación no existe
40358	Incoherencia del ID de conversación
40364	El agente no admite la modalidad de imagen
50000	Error interno del sistema
20040	Se ha superado el límite de longitud de la pregunta
20022	Créditos insuficientes
20055	Uso de la API prohibido; asegúrese de que el conmutador de API está habilitado