Hướng dẫn Tích hợp API GPT Conversation vào GPT Speak Up

1. Tổng quan

Tài liệu này mô tả cách tích hợp API GPT Conversation để tạo ra luồng hội thoại tương tác giữa Bot (máy) và Người dùng trong tính năng GPT Speak Up. Luồng hội thoại được thiết kế theo lượt: Bot sẽ nói trước, sau đó Người dùng trả lời.

2. Thông tin API Endpoint

• URL: https://videocall.monkeyenglish.net/
• Method: POST
• Header:
  • Dev: Bỏ qua Header (Không cần xác thực).
  • Live: Sẽ sử dụng JWT (JSON Web Token) để xác thực. Dev có thể chuẩn bị cấu trúc để thêm JWT sau.
• Body Type: multipart/form-data

3. Tham số Request (Form Data)

4. Luồng Hội thoại và Cách gọi API

Luồng hội thoại bao gồm ít nhất 2 lượt: Bot bắt đầu, Người dùng trả lời.

Lượt 1: Bắt đầu hội thoại (Bot nói trước)

• Mục đích: Lấy câu nói/câu hỏi đầu tiên từ Bot.
• Cách gọi API:
  • Gửi request POST đến URL API.
  • Tham số:
    • command: "reply"
    • topic_id: {ID chủ đề bạn muốn bắt đầu} (ví dụ: "3")
    • session_id: "" (Để trống vì đây là lượt đầu)
    • user_answer: "" (Để trống vì Bot nói trước)
• Ví dụ Request (curl):

  curl --location 'https://lipsync.monkeyenglish.net/api/chat' \
  --form 'command="reply"' \
  --form 'topic_id="3"' \
  --form 'session_id=""' \
  --form 'user_answer=""'
  

• Xử lý Response:
  1. Nhận response JSON từ API.
  2. Hiển thị/Phát câu nói của Bot: Sử dụng text trong reply.response[0] và/hoặc phát audio từ reply.audio_url[0]. Lưu ý: question.question cũng chứa text tương tự.
  3. Lưu lại session_id: Lấy giá trị id từ session.id trong response. Session ID này BẮT BUỘC phải được sử dụng cho lượt gọi API tiếp theo để duy trì mạch hội thoại.
  4. Chờ người dùng nhập/nói câu trả lời.

Lượt 2 trở đi: Người dùng trả lời

• Mục đích: Gửi câu trả lời của người dùng và nhận phản hồi tiếp theo từ Bot.
• Cách gọi API:
  • Gửi request POST đến URL API.
  • Tham số:
    • command: "reply"
    • topic_id: {ID chủ đề đang diễn ra} (giống lượt 1)
    • session_id: {Session ID đã lưu từ response trước đó} (ví dụ: "70489c7ffef345cc8f8da5cdff260df2")
    • user_answer: {Câu trả lời của người dùng} (ví dụ: "My name is Trung")
• Ví dụ Request (curl):

  curl --location 'https://lipsync.monkeyenglish.net/api/chat' \
  --form 'command="reply"' \
  --form 'topic_id="3"' \
  --form 'session_id="70489c7ffef345cc8f8da5cdff260df2"' \
  --form 'user_answer="My name is TRung"'
  

• Xử lý Response:
  1. Nhận response JSON từ API.
  2. Kiểm tra kết thúc hội thoại: Kiểm tra giá trị session.is_last.
     • Nếu is_last == true: Hội thoại đã kết thúc. Hiển thị/phát câu nói cuối cùng của Bot (nếu có trong reply) và kết thúc luồng.
     • Nếu is_last == false: Hội thoại tiếp tục.
  3. Hiển thị/Phát câu nói của Bot: Sử dụng text trong reply.response[0] và/hoặc phát audio từ reply.audio_url[0].
  4. Lưu lại session_id mới: Lấy giá trị id từ session.id trong response hiện tại để sử dụng cho lượt gọi tiếp theo.
  5. Chờ người dùng nhập/nói câu trả lời tiếp theo. Lặp lại quy trình Lượt 2.

5. Cấu trúc Response (JSON)

API trả về một đối tượng JSON với cấu trúc như sau:

{
   "session": {
       "id": "70489c7ffef345cc8f8da5cdff260df2", // ID phiên, dùng cho request tiếp theo
       "conversation_id": 3,                  // ID của chủ đề hội thoại
       "is_last": false                       // true: Lượt cuối cùng, false: Còn tiếp
   },
   "question": {                              // Thông tin về câu hỏi/lời nói *hiện tại* của Bot
       "id": 5,
       "question": "Hi",                       // Nội dung text câu hỏi/lời nói của Bot
       "media_url": null                     // URL media bổ sung (nếu có)
   },
   "reply": {                                 // Phản hồi cụ thể của Bot cho lượt này
       "response": [                          // List các chuỗi text phản hồi (thường là 1)
           "Hi"
       ],
       "audio_url": [                         // List các URL file audio tương ứng với 'response'
           "https://vysqy4zclvobj.vcdn.cloud/test/mspeak_dialog/AUwyB3420Kewpmr5lB9FP4Ikf.wav"
       ]
   },
   "user_answer": "My name is TRung"          // Câu trả lời của người dùng đã gửi trong request (dùng để kiểm tra)
}

Giải thích các thành phần chính trong Response:

• session: Chứa thông tin về phiên hội thoại.
  • id: Rất quan trọng. Đây là session_id cần được gửi lại trong request tiếp theo để duy trì liên tục cuộc trò chuyện.
  • conversation_id: ID của topic đang hội thoại.
  • is_last: Cờ báo hiệu lượt trả lời này có phải là lượt cuối cùng của hội thoại hay không. Nếu true, ứng dụng nên kết thúc luồng hội thoại sau khi xử lý phản hồi này.
• question: Chứa thông tin về lời nói/câu hỏi hiện tại của Bot trong lượt này.
  • question: Nội dung text của lời nói/câu hỏi.
• reply: Chứa nội dung phản hồi chi tiết của Bot.
  • response: Một mảng (list) các chuỗi text. Thông thường chỉ chứa 1 phần tử là câu trả lời/phản hồi của Bot.
  • audio_url: Một mảng (list) các URL audio tương ứng với các phần tử trong response. Thường chỉ chứa 1 URL file audio đã được gộp sẵn, tương ứng với toàn bộ nội dung text trong response. Ứng dụng có thể phát file audio này.
• user_answer: Trả lại chính xác giá trị user_answer mà client đã gửi lên trong request, hữu ích cho việc debug hoặc xác nhận.

6. Lưu ý quan trọng

• Quản lý session_id: Việc gửi đúng session_id (trống cho lượt đầu, giá trị từ response trước cho các lượt sau) là then chốt để duy trì ngữ cảnh hội thoại. Nếu gửi sai hoặc luôn gửi trống, API sẽ coi đó là bắt đầu một hội thoại mới.
• Xử lý is_last: Luôn kiểm tra cờ is_last trong response để biết khi nào nên kết thúc luồng hội thoại một cách hợp lý.
• Sử dụng reply: Ưu tiên sử dụng dữ liệu trong reply (response cho text, audio_url cho audio) để hiển thị/phát phản hồi của Bot cho người dùng.

Hy vọng tài liệu này giúp bạn tích hợp API dễ dàng hơn. Nếu có bất kỳ điểm nào chưa rõ, hãy hỏi lại nhé!