AI助手集成常见问题

全局参数（isGlobal: true）

• 持久化存储：设置后会一直保留，直到被新的全局参数覆盖。

• 每次发送都携带：每次发送消息时都会自动携带这些参数。

• 适用场景：用户身份信息、会话级别的配置等需要持续传递的数据。

// 设置全局参数 - 这些参数会在每次发送消息时都携带
window.APPFLOW_CHAT_SDK.setExtraInfo({
  tenantId: 'tenant-001',
  channel: 'web',
  language: 'zh-CN',
}, true); // isGlobal = true

临时参数（isGlobal: false 或不传）

• 使用：在下一次发送消息时携带。

• 适用场景：特定消息的上下文信息、一次性的业务数据。

// 设置临时参数 - 仅在下一次发送消息时携带
window.APPFLOW_CHAT_SDK.setExtraInfo({
  currentPage: '/product/detail',
  productId: 'SKU-12345',
  timestamp: Date.now(),
}); // isGlobal 默认为 false

// 或者显式指定
window.APPFLOW_CHAT_SDK.setExtraInfo({
  orderId: 'ORDER-001',
}, false);

text 类型（普通文本消息）

{
  messageType: 'text',
  sessionId: string,
  chatbotId: string,
  chatbotModelId: string,
  text: {
    content: string  // 用户输入的文本内容
  },
  userInfo?: object,
  extraInfo?: object,
  config?: object
}

rich 类型（富文本消息）

包含文本、图片、文件等多媒体内容的消息。

{
  messageType: 'rich',
  sessionId: string,
  chatbotId: string,
  chatbotModelId: string,
  richText: Array<{
    type: 'text' | 'image' | 'file',
    content?: string,      // type='text' 时的文本内容
    mediaUrl?: string,     // type='image' 或 'file' 时的媒体URL
    mediaId?: string       // type='file' 时的文件ID（可选）
  }>,
  userInfo?: object,
  extraInfo?: object,
  config?: object
}

audio 类型（语音消息）

{
  messageType: 'audio',
  sessionId: string,
  chatbotId: string,
  chatbotModelId: string,
  audio: {
    mediaUrl: string,    // 音频文件URL
    mediaType: string    // 音频类型，如 'wav'
  },
  userInfo?: object,
  extraInfo?: object,
  config?: object
}

event 类型（系统事件）

{
  messageType: 'event',
  sessionId: string,
  chatbotModelId: string,
  event: {
    eventType: string,  // 事件类型，如 'uploadFile'
    content: string     // 事件内容（JSON字符串）
  }
}

card_call_back 类型（卡片回调）

用于审批等交互场景。

{
  messageType: 'card_call_back',
  sessionId: string,
  cardCallBack: {
    data: any  // 卡片回调数据
  }
}

同步模式（默认）

处理器函数执行后，立即发送消息。即使处理器返回 Promise，也不会等待 Promise 完成。适用于简单的日志记录、数据统计等不需要阻塞发送的场景

// 同步模式 - 处理器执行后立即发送消息
window.APPFLOW_CHAT_SDK.onBeforeSend((params) => {
  console.log('用户即将发送消息:', params.userMessage);
  
  // 记录埋点（不阻塞发送）
  analytics.track('message_send', {
    content: params.userMessage,
    timestamp: Date.now(),
  });
});

异步模式（async: true）

处理器函数返回 Promise 时，会等待 Promise 完成后再发送消息。适用于需要在发送前进行异步操作的场景，如内容审核、数据预处理等。

// 异步模式 - 等待处理器完成后再发送消息
window.APPFLOW_CHAT_SDK.onBeforeSend(async (params) => {
  console.log('用户即将发送消息:', params.userMessage);
  
  // 异步操作：内容审核
  const isValid = await contentModeration.check(params.userMessage);
  if (!isValid) {
    throw new Error('消息内容不合规');
  }
  
  // 异步操作：设置动态参数
  const contextData = await fetchUserContext();
  window.APPFLOW_CHAT_SDK.setExtraInfo({
    context: contextData,
  });
}, { async: true });

示例 1：简单日志记录（同步）

window.APPFLOW_CHAT_SDK.onBeforeSend((params) => {
  console.log(`[${new Date().toISOString()}] 发送消息: ${params.userMessage}`);
});

示例 2：动态设置额外参数（同步）

window.APPFLOW_CHAT_SDK.onBeforeSend((params) => {
  // 根据消息内容动态设置参数
  const keywords = extractKeywords(params.userMessage);
  
  window.APPFLOW_CHAT_SDK.setExtraInfo({
    keywords: keywords,
    messageLength: params.userMessage.length,
    sendTime: Date.now(),
  });
});

示例 3：异步内容预处理（异步）

window.APPFLOW_CHAT_SDK.onBeforeSend(async (params) => {
  // 调用后端接口获取用户上下文
  const response = await fetch('/api/user/context');
  const userContext = await response.json();
  
  // 设置额外参数
  window.APPFLOW_CHAT_SDK.setExtraInfo({
    userContext: userContext,
    processedAt: Date.now(),
  });
}, { async: true });

成功时的参数

失败时的参数

同步模式（默认）

处理器函数执行后，不会阻塞后续操作即使处理器返回 Promise，也不会等待 Promise 完成。适用于日志记录、数据统计、UI 更新等不需要阻塞的场景。

// 同步模式
window.APPFLOW_CHAT_SDK.onAfterSend((params) => {
  if (params.success) {
    console.log('消息发送成功');
    console.log('AI 回复:', params.assistantContent);
  } else {
    console.error('消息发送失败:', params.error.message);
  }
});

异步模式（async: true）

处理器函数返回 Promise 时，会等待 Promise 完成，适用于需要在回复完成后进行异步操作的场景，如数据持久化、后续 API 调用等。

// 异步模式
window.APPFLOW_CHAT_SDK.onAfterSend(async (params) => {
  if (params.success) {
    // 异步保存对话记录
    await saveConversation({
      question: params.userMessage,
      answer: params.assistantContent,
      references: params.assistantReferences,
    });
  }
}, { async: true });

示例 1：基础日志记录

window.APPFLOW_CHAT_SDK.onAfterSend((params) => {
  const timestamp = new Date().toISOString();
  
  if (params.success) {
    console.log(`[${timestamp}] 对话完成`);
    console.log(`  用户: ${params.userMessage}`);
    console.log(`  AI: ${params.assistantContent.substring(0, 100)}...`);
    console.log(`  引用数量: ${params.assistantReferences.length}`);
  } else {
    console.error(`[${timestamp}] 对话失败`);
    console.error(`  用户: ${params.userMessage}`);
    console.error(`  错误: [${params.error.code}] ${params.error.message}`);
  }
});

示例 2：数据埋点统计

window.APPFLOW_CHAT_SDK.onAfterSend((params) => {
  // 发送埋点数据
  analytics.track('chat_completed', {
    success: params.success,
    userMessage: params.userMessage,
    responseLength: params.success ? params.assistantContent.length : 0,
    referenceCount: params.success ? params.assistantReferences.length : 0,
    timestamp: Date.now(),
  });
});

示例 3：对话记录持久化（异步）

window.APPFLOW_CHAT_SDK.onAfterSend(async (params) => {
  try {
    await fetch('/api/conversation/save', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        question: params.userMessage,
        answer: params.success ? params.assistantContent : null,
        references: params.success ? params.assistantReferences : [],
        error: params.success ? null : params.error,
        timestamp: Date.now(),
      }),
    });
  } catch (error) {
    console.error('保存对话记录失败:', error);
  }
}, { async: true });