ส่งข้อความ
ใช้ 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"
}
}
}'
หมายเหตุสำคัญ:
- สำหรับเนื้อหา
image,audioและdocumentสามารถใช้ได้ทั้งแบบ base64 หรือ URL - รองรับทั้งสองรูปแบบ - นักพัฒนาต้องส่งเฉพาะข้อความล่าสุดของผู้ใช้เท่านั้น เพราะ 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: |
| messages | JSON Array | ใช่ | เนื้อหาข้อความ รองรับบทบาท user และ assistant เพื่อสร้างบริบทการสนทนา |
| 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 จะใช้ค่าตั้งต้นของ Agentgroup_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
}
}
}
การตอบกลับสำเร็จ (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":"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 โปรดดูที่ Webhook Mode และ human handoff service
การตอบกลับผิดพลาด
| ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
| code | int | รหัสข้อผิดพลาด |
| message | string | รายละเอียดข้อผิดพลาด |
รหัสข้อผิดพลาด
| รหัส | ข้อความ |
|---|---|
| 40000 | พารามิเตอร์ไม่ถูกต้อง |
| 40127 | การยืนยันตัวตนของนักพัฒนาไม่ผ่าน |
| 40356 | ไม่พบการสนทนา |
| 40358 | conversation_id ไม่ตรงกัน |
| 40364 | Agent ไม่รองรับภาพ |
| 50000 | ข้อผิดพลาดภายในระบบ |
| 20040 | เกินขีดจำกัดความยาวคำถาม |
| 20022 | เครดิตไม่เพียงพอ |
| 20055 | ไม่อนุญาตให้ใช้ API โปรดตรวจสอบว่าเปิดใช้งาน API แล้ว |

