ส่งข้อความ

ส่งข้อความ

ใช้ 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", "user_id": "65a4ccfc7ce58e728d5897e0", "anonymous_id": "device_abcdef123456", "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",
        "user_id": "65a4ccfc7ce58e728d5897e0",
        "anonymous_id": "device_abcdef123456",
        "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

    ฟิลด์ ประเภท คำอธิบาย
    user_id string รหัสผู้ใช้ที่นักพัฒนาผูกไว้ จะเป็น null เมื่อไม่มีผู้ใช้ผูกอยู่
    anonymous_id string รหัสผู้ใช้ที่ไม่ระบุตัวตน (อุปกรณ์)
    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)

    หลังจากที่นักพัฒนากำหนดค่าที่อยู่ webhook ในส่วน «การเชื่อมต่อ-API» เรียบร้อยแล้ว ระบบ GPTBots จะส่งข้อความ «การตอบกลับของ Agent» และ «การตอบกลับของเจ้าหน้าที่บริการที่เป็นมนุษย์» ไปยังที่อยู่ webhook
    webhook config
    สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับข้อความ webhook โปรดดูที่ การรับข้อความผ่าน Webhook และ human handoff service

    ⚠️ ในโหมด API หากเปิดใช้งานบริการส่งต่อให้เจ้าหน้าที่ที่เป็นมนุษย์ คุณต้องใช้โหมดการตอบกลับ webhook จึงจะสามารถรับข้อความตอบกลับจากเจ้าหน้าที่บริการที่เป็นมนุษย์ได้

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

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

    ตัวอย่างการตอบกลับผิดพลาด

    { "code": 40000, "message": "พารามิเตอร์ไม่ถูกต้อง", "errors": [ { "error_code": 40000, "error_message": "Message user role type must have file or content." } ], "data": { "create_time": 1679587005, "conversation_id": "657303a8a764d47094874bbe", "user_id": "65a4ccfc7ce58e728d5897e0", "anonymous_id": "device_abcdef123456", "message_id": "65a4ccfC7ce58e728d5897e0", "output": [ { "from_component_branch": "1", "from_component_name": "Component Name", "content": { "text": "ได้ตอบกลับตามเนื้อหาที่สามารถจดจำได้……", "audio": null } } ], "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, "text_input_credits": 0, "text_output_credits": 0, "audio_input_credits": 0, "audio_output_credits": 0 } } } }
                          
                          {
      "code": 40000,
      "message": "พารามิเตอร์ไม่ถูกต้อง",
      "errors": [
        {
          "error_code": 40000,
          "error_message": "Message user role type must have file or content."
        }
      ],
      "data": {
        "create_time": 1679587005,
        "conversation_id": "657303a8a764d47094874bbe",
        "user_id": "65a4ccfc7ce58e728d5897e0",
        "anonymous_id": "device_abcdef123456",
        "message_id": "65a4ccfC7ce58e728d5897e0",
        "output": [
          {
            "from_component_branch": "1",
            "from_component_name": "Component Name",
            "content": {
              "text": "ได้ตอบกลับตามเนื้อหาที่สามารถจดจำได้……",
              "audio": null
            }
          }
        ],
        "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,
            "text_input_credits": 0,
            "text_output_credits": 0,
            "audio_input_credits": 0,
            "audio_output_credits": 0
          }
        }
      }
    }
    
                        
    บล็อกโค้ดนี้ในหน้าต่างลอย

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

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