ส่งข้อความ

ส่งข้อความ

ใช้ API นี้เพื่อส่งข้อความไปยัง conversation_id ที่ระบุและรับการตอบกลับที่สร้างโดย Agent API รองรับเนื้อหาข้อความหลายประเภท เช่น ข้อความตัวอักษร, รูปภาพ, เสียง และเอกสาร

วิธีการร้องขอ

POST

Endpoint

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

การยืนยันตัวตน

โปรดดูที่ ภาพรวม API สำหรับคำแนะนำการยืนยันตัวตน

การร้องขอ

ตัวอย่างการร้องขอ

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"
        }
    }
}'

                    
บล็อกโค้ดนี้ในหน้าต่างลอย

หมายเหตุสำคัญ:

  1. สำหรับเนื้อหา image, audio และ document สามารถใช้ได้ทั้งแบบ base64 หรือ URL - รองรับทั้งสองรูปแบบ
  2. นักพัฒนาต้องส่งเฉพาะข้อความล่าสุดของผู้ใช้เท่านั้น เพราะ GPTBots จะจัดการ short-term และ long-term memory ให้อัตโนมัติ หากต้องการปรับ context ของ short-term memory ดูตัวอย่างด้านล่าง:
    "messages": [ { "role": "user", "content": "Hello" //ปรับแต่ง short-term memory }, { "role": "assistant", "content": "Hello! How can I assist you today?" //ปรับแต่ง short-term memory }, { "role": "user", "content": "Hello" //ข้อความล่าสุดของผู้ใช้ }]
                          
                              "messages": [
            {
                "role": "user", 
                "content": "Hello"                                //ปรับแต่ง short-term memory
            },
            {
                "role": "assistant",
                "content": "Hello! How can I assist you today?"   //ปรับแต่ง short-term memory
            },
            {
                "role": "user",
                "content": "Hello"                                //ข้อความล่าสุดของผู้ใช้
            }]
    
                        
    บล็อกโค้ดนี้ในหน้าต่างลอย

Request Headers

ฟิลด์ ประเภท คำอธิบาย
Authorization Bearer ${API Key} ใช้ Authorization: Bearer ${API Key} สำหรับการยืนยันตัวตน รับ API Key ได้จากหน้า API Key
Content-Type application/json ประเภทข้อมูล ต้องเป็น application/json

พารามิเตอร์การร้องขอ

ฟิลด์ ประเภท จำเป็น คำอธิบาย
conversation_id string ใช่ รหัสสนทนา ต้องระบุ conversation_id เพื่อดำเนินการสนทนาต่อ
response_mode string ใช่ โหมดการตอบกลับของ Agent:
  • blocking: รอจนเสร็จและคืนผลลัพธ์ (อาจถูกขัดจังหวะหากใช้เวลานานเกินไป)
  • streaming: ส่งผลลัพธ์แบบสตรีมด้วย SSE (Server-Sent Events)
  • webhook: ข้อความจาก Agent และเจ้าหน้าที่บริการลูกค้าจะถูกส่งไปยัง webhook URL ที่ตั้งค่าไว้ในหน้า API
  • messages JSON Array ใช่ เนื้อหาข้อความ รองรับบทบาท user และ assistant เพื่อสร้างบริบทการสนทนา
  • user message: ต้องมีอย่างน้อย 1 รายการ ข้อความล่าสุดต้องอยู่ท้ายสุด
  • assistant message: นักพัฒนาสามารถสร้างข้อความของ assistant เพื่อใช้เป็น context ได้
  • conversation_config object ไม่จำเป็น ปรับขอบเขตฟังก์ชันของ Agent ชั่วคราวสำหรับการสนทนานี้เพื่อรองรับความต้องการพิเศษ
    short_term_memory boolean ไม่จำเป็น เปิด/ปิด short-term memory สำหรับการสนทนานี้เท่านั้น
    long_term_memory boolean ไม่จำเป็น เปิด/ปิด long-term memory สำหรับการสนทนานี้เท่านั้น
    knowledge object ไม่จำเป็น ขอบเขตการค้นหาความรู้ กำหนดขอบเขตการค้นหาความรู้เฉพาะสำหรับการสนทนานี้ หากระบุทั้ง group_ids และ data_ids จะค้นหาในฐานความรู้รวมกัน หากทั้งสองเป็นอาร์เรย์ว่างจะไม่ดึงความรู้ใด ๆ ถ้าไม่ระบุ knowledge จะใช้ค่าตั้งต้นของ Agent
  • group_ids: รหัสฐานความรู้
  • data_ids: รหัสเอกสารในฐานความรู้
  • custom_variables object ไม่จำเป็น ตัวแปรกำหนดเอง ปรับค่าตัวแปรของ Agent สำหรับการสนทนานี้เท่านั้น

    หมายเหตุ:

    หน้า configuration input/output ของ Agent รองรับรูปแบบการรับรู้ที่ต่างกันสำหรับแต่ละประเภทข้อความ ประเภทไฟล์และขนาดที่รองรับอาจแตกต่างกัน โปรดปรับข้อมูล API ให้เหมาะสมกับแต่ละกรณี รูปแบบข้อความที่รองรับสูงสุด:

    • ข้อความ: string
    • เสียง: .mp3, .wav, .acc
    • รูปภาพ: .jpg, .jpeg, .png, .gif, .webp
    • เอกสาร: .pdf, .txt, .docx, .csv, .xlsx, .html, .json, .md, .tex, .ts, .xml ฯลฯ

    การตอบกลับ

    ตัวอย่างการตอบกลับ

    { "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
            }
        }
    }
    
                        
    บล็อกโค้ดนี้ในหน้าต่างลอย

    การตอบกลับสำเร็จ (Blocking)

    ⚠️ ไม่รองรับ human handoff ในโหมด blocking

    ฟิลด์ ประเภท คำอธิบาย
    conversation_id string ใช่
    message_id string รหัสข้อความเฉพาะในแต่ละสนทนา
    create_time long เวลาที่สร้างข้อความตอบกลับนี้ (timestamp)
    output JSON Array เนื้อหาการตอบกลับของ Agent
    from_component_branch string สาขา FlowAgent
    from_component_name string ชื่อ component ต้นทางใน FlowAgent
    content object เนื้อหาข้อความที่ AI Agent ตอบกลับ ปัจจุบันรองรับ 2 ประเภทคือ text และ audio
    usage object รายละเอียดการใช้ทรัพยากร
    tokens JSON Array จำนวนโทเคนที่ Agent ใช้ในสนทนานี้ทั้งหมด
    total_tokens integer จำนวนโทเคนรวมที่ใช้ทั้ง input และ output
    prompt_tokens integer จำนวนโทเคน input ที่ใช้
    completion_tokens integer จำนวนโทเคน output ที่ใช้
    prompt_tokens_details object รายละเอียดโทเคน input
    completion_tokens_details object รายละเอียดโทเคน output
    credits object เครดิตที่ Agent ใช้ในสนทนานี้ทั้งหมด
    text_input_credits double เครดิตที่ใช้สำหรับข้อความ input
    text_output_credits double เครดิตที่ใช้สำหรับข้อความ output
    audio_input_credits double เครดิตที่ใช้สำหรับเสียง input
    audio_output_credits double เครดิตที่ใช้สำหรับเสียง output

    การตอบกลับสำเร็จ (Streaming)

    ⚠️ ไม่รองรับ human handoff ในโหมด streaming

    ฟิลด์ ประเภท คำอธิบาย
    code int รหัสประเภทข้อความ: 3-ข้อความ, 10-ผลลัพธ์ FlowAgent, 0-จบ, 4-ข้อมูลการใช้, 39-ข้อความเสียง
    message string ประเภทข้อความ: Text, FlowOutput, End
    data object เนื้อหาการตอบกลับ
    • ตัวอย่างการสตรีมข้อความ:
    {"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}
    
                        
    บล็อกโค้ดนี้ในหน้าต่างลอย
    • ตัวอย่างการสตรีมข้อความเสียง:
    {"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}
    
                        
    บล็อกโค้ดนี้ในหน้าต่างลอย

    การตอบกลับสำเร็จ (Webhook)

    ⚠️ รองรับ human handoff ในโหมด webhook
    หากเปิดใช้งาน human customer service สำหรับ Agent ควรใช้โหมด webhook เพื่อรับข้อความจากเจ้าหน้าที่บริการลูกค้าจริง หลังจากตั้งค่า webhook URL ในหน้า "Integration-API" ระบบ GPTBots จะส่งข้อความตอบกลับจากทั้ง "Agent" และ "เจ้าหน้าที่บริการลูกค้า" ไปยัง webhook URL ของคุณ
    webhook config
    สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับข้อความ webhook โปรดดูที่ Webhook Mode และ human handoff service

    การตอบกลับผิดพลาด

    ฟิลด์ ประเภท คำอธิบาย
    code int รหัสข้อผิดพลาด
    message string รายละเอียดข้อผิดพลาด

    รหัสข้อผิดพลาด

    รหัส ข้อความ
    40000 พารามิเตอร์ไม่ถูกต้อง
    40127 การยืนยันตัวตนของนักพัฒนาไม่ผ่าน
    40356 ไม่พบการสนทนา
    40358 conversation_id ไม่ตรงกัน
    40364 Agent ไม่รองรับภาพ
    50000 ข้อผิดพลาดภายในระบบ
    20040 เกินขีดจำกัดความยาวคำถาม
    20022 เครดิตไม่เพียงพอ
    20055 ไม่อนุญาตให้ใช้ API โปรดตรวจสอบว่าเปิดใช้งาน API แล้ว