Gửi Câu Hỏi Cho AI (ExampleSendAiMessage)

MUTATION MẪU Yêu cầu Bearer Token

🛡️ Lưu Ý Schema Mẫu: Tài liệu này mô tả định dạng mutation mẫu (Example Mutation). Cấu trúc schema và tên trường chính thức sẽ được cấp riêng trong tài liệu hợp tác.

Gửi câu hỏi của người dùng tới mô hình AI. Hệ thống sẽ tiếp nhận yêu cầu và phản hồi ngay lập tức các mã định danh (session_id, assistant_msg_id, client_request_key) để Client kết nối Firebase Firestore nhận stream câu trả lời.

Non-Blocking Architecture

API này không đợi AI sinh toàn bộ câu trả lời mới trả về HTTP response. Do đó, request hoàn tất rất nhanh (thường dưới 300ms), loại bỏ hoàn toàn nguy cơ HTTP Timeout khi người dùng đặt câu hỏi phức tạp.

💻 Chi Tiết Truy Vấn & Mã Nguồn Mẫu

GraphQL Mutation & Payload (Mẫu):

GraphQL Mutation

ExampleSendAiMessage.gql

mutation ExampleSendAiMessage($input: ExampleSendMessageInput!, $attachments: [Upload!]) {
  exampleSendAiMessage(input: $input, attachments: $attachments) {
    session_id
    request_token_id
    client_request_key
    user_msg_id
    assistant_msg_id
    channel_source
    stream_status
  }
}

Variables (JSON Mẫu)

Variables

{
  "input": {
    "prompt_message": "Pango AI hỗ trợ các giải pháp và kênh tích hợp nào cho doanh nghiệp?",
    "app_channel": "WEB_APP",
    "session_id": null,
    "bot_code": "ai_assistant",
    "conversation_topic": "qa",
    "client_request_key": "idem_1740200010000_abc1234"
  },
  "attachments": []
}

Phản Hồi Thành Công (JSON Response Mẫu)

Response 200 OK

{
  "data": {
    "exampleSendAiMessage": {
      "session_id": "sess_89f1a23b4c5d6e7f",
      "request_token_id": "req_1740200010000_abc1234",
      "client_request_key": "idem_1740200010000_abc1234",
      "user_msg_id": "msg_usr_01j89a8bc43d",
      "assistant_msg_id": "msg_ast_01j89a8bc43e",
      "channel_source": "WEB_APP",
      "stream_status": "PROCESSING"
    }
  }
}

TypeScript / Axios:

exampleSendAiMessage.ts

import axios from 'axios';

export interface ExampleSendMessageInput {
  prompt_message: string;
  app_channel: string;
  session_id?: string | null;
  bot_code: string;
  conversation_topic?: string;
  client_request_key: string;
}

export interface ExampleMessageDispatchPayload {
  session_id: string;
  request_token_id: string;
  client_request_key: string;
  user_msg_id: string;
  assistant_msg_id: string;
  channel_source: string;
  stream_status: 'PROCESSING' | 'COMPLETED' | 'FAILED';
}

/**
 * Gửi câu hỏi của người dùng tới Pango AI Chatbot (Mã mẫu)
 * @param apiUrl Endpoint GraphQL Gateway
 * @param token JWT Access Token sau khi đăng nhập
 * @param prompt Nội dung câu hỏi người dùng nhập
 * @param activeSessionId Session ID hiện tại (null nếu là câu hỏi mở đầu phiên mới)
 * @param botCode Mã định danh agent (mặc định 'ai_assistant')
 * @param channel Kênh gửi tin ('WEB_APP' | 'MOBILE_APP')
 */
export async function exampleSendAiMessage(
  apiUrl: string = process.env.VITE_API_URL!,
  token: string,
  prompt: string,
  activeSessionId: string | null = null,
  botCode: string = 'ai_assistant',
  channel: string = 'WEB_APP'
): Promise<ExampleMessageDispatchPayload> {
  const query = `
    mutation ExampleSendAiMessage($input: ExampleSendMessageInput!, $attachments: [Upload!]) {
      exampleSendAiMessage(input: $input, attachments: $attachments) {
        session_id
        request_token_id
        client_request_key
        user_msg_id
        assistant_msg_id
        channel_source
        stream_status
      }
    }
  `;

  // Tạo khóa Idempotency duy nhất chống gửi trùng
  const idempotencyKey = `idem_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;

  const variables = {
    input: {
      prompt_message: prompt,
      app_channel: channel,
      session_id: activeSessionId || null,
      bot_code: botCode,
      conversation_topic: 'qa',
      client_request_key: idempotencyKey,
    },
    attachments: [],
  };

  const response = await axios.post(
    apiUrl,
    {
      query,
      variables,
      operationName: 'ExampleSendAiMessage',
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
        'x-org-id': process.env.VITE_ORG_ID || 'org_sample_demo',
        'x-client-type': 'app',
        'x-external-private-key': process.env.VITE_EXTERNAL_PRIVATE_KEY || 'your_secret_key',
      },
    }
  );

  return response.data?.data?.exampleSendAiMessage;
}

📑 Bảng Tham Số Mẫu (Example Schema Definition)

`ExampleSendMessageInput`

Thuộc Tính Mẫu	Kiểu Dữ Liệu	Bắt Buộc	Mô Tả
`prompt_message`	`String!`	Có	Nội dung câu hỏi người dùng nhập
`app_channel`	`String!`	Có	Định danh kênh gửi (`"WEB_APP"`, `"MOBILE_APP"`)
`session_id`	`String`	Không	ID phiên chat đang tiếp diễn. Nếu gửi `null`, hệ thống tự sinh phiên mới
`bot_code`	`String!`	Có	Mã bot (ví dụ: `"ai_assistant"`)
`conversation_topic`	`String`	Không	Chủ đề hội thoại (mặc định `"qa"`)
`client_request_key`	`String!`	Có	Khóa chống lặp (UUID hoặc chuỗi ngẫu nhiên có timestamp)

Dữ Liệu Trả Về (`ExampleMessageDispatchPayload`)

Thuộc Tính Mẫu	Kiểu Dữ Liệu	Mô Tả
`session_id`	`String!`	ID phiên chat (Lưu lại để gửi kèm các tin nhắn sau)
`assistant_msg_id`	`String!`	Rất quan trọng: ID tin nhắn của bot dùng để lắng nghe Stream trên Firestore
`user_msg_id`	`String!`	ID tin nhắn của người dùng trong hệ cơ sở dữ liệu
`stream_status`	`String!`	Trạng thái ban đầu (`"PROCESSING"`)