AI assistant integration FAQ

Global parameters (isGlobal: true)

• Persistence: Retained until overwritten by new global parameters.

• Sent with every message: Automatically included in every message request.

• Use case: For data that needs to be passed continuously, such as user identity information or session-level configurations.

// Set global parameters. These parameters are sent with every message.
window.APPFLOW_CHAT_SDK.setExtraInfo({
  tenantId: 'tenant-001',
  channel: 'web',
  language: 'zh-CN',
}, true); // isGlobal = true

Temporary parameters (isGlobal: false or omitted)

• Scope: Included with the next message only.

• Use case: For message-specific context or one-time business data.

// Set temporary parameters. These are sent only with the next message.
window.APPFLOW_CHAT_SDK.setExtraInfo({
  currentPage: '/product/detail',
  productId: 'SKU-12345',
  timestamp: Date.now(),
}); // isGlobal defaults to false

// Or, specify it explicitly
window.APPFLOW_CHAT_SDK.setExtraInfo({
  orderId: 'ORDER-001',
}, false);

text (plain text message)

{
  messageType: 'text',
  sessionId: string,
  chatbotId: string,
  chatbotModelId: string,
  text: {
    content: string  // The text content entered by the user
  },
  userInfo?: object,
  extraInfo?: object,
  config?: object
}

rich (rich text message)

A message that contains multimedia content, such as text, images, and files.

{
  messageType: 'rich',
  sessionId: string,
  chatbotId: string,
  chatbotModelId: string,
  richText: Array<{
    type: 'text' | 'image' | 'file',
    content?: string,      // Text content if type='text'
    mediaUrl?: string,     // Media URL if type='image' or 'file'
    mediaId?: string       // Optional file ID if type='file'
  }>,
  userInfo?: object,
  extraInfo?: object,
  config?: object
}

audio (audio message)

{
  messageType: 'audio',
  sessionId: string,
  chatbotId: string,
  chatbotModelId: string,
  audio: {
    mediaUrl: string,    // Audio file URL
    mediaType: string    // Audio type, for example, 'wav'
  },
  userInfo?: object,
  extraInfo?: object,
  config?: object
}

event (system event)

{
  messageType: 'event',
  sessionId: string,
  chatbotModelId: string,
  event: {
    eventType: string,  // Event type, for example, 'uploadFile'
    content: string     // Event content (a JSON string)
  }
}

card_call_back (card callback)

Used for interactive scenarios, such as approvals.

{
  messageType: 'card_call_back',
  sessionId: string,
  cardCallBack: {
    data: any  // Card callback data
  }
}

Synchronous mode (default)

After the processor function executes, the SDK sends the message immediately. Even if the function returns a Promise, the SDK does not wait for it to resolve. This mode is suitable for non-blocking tasks like logging or analytics.

// Synchronous mode: The message is sent immediately after the handler executes.
window.APPFLOW_CHAT_SDK.onBeforeSend((params) => {
  console.log('User is about to send a message:', params.userMessage);
  
  // Track analytics (non-blocking).
  analytics.track('message_send', {
    content: params.userMessage,
    timestamp: Date.now(),
  });
});

Asynchronous mode (async: true)

If the processor function returns a Promise, the SDK waits for the Promise to resolve before sending the message. This mode is suitable for asynchronous operations that must complete before the message is sent, such as content moderation or data preprocessing.

// Asynchronous mode: The SDK waits for the handler to complete before sending the message.
window.APPFLOW_CHAT_SDK.onBeforeSend(async (params) => {
  console.log('User is about to send a message:', params.userMessage);
  
  // Asynchronous operation: content moderation.
  const isValid = await contentModeration.check(params.userMessage);
  if (!isValid) {
    throw new Error('Message content is not compliant');
  }
  
  // Asynchronous operation: set dynamic parameters.
  const contextData = await fetchUserContext();
  window.APPFLOW_CHAT_SDK.setExtraInfo({
    context: contextData,
  });
}, { async: true });

Example 1: Simple logging

window.APPFLOW_CHAT_SDK.onBeforeSend((params) => {
  console.log(`[${new Date().toISOString()}] Sending message: ${params.userMessage}`);
});

Example 2: Set dynamic parameters

window.APPFLOW_CHAT_SDK.onBeforeSend((params) => {
  // Dynamically set parameters based on the message content.
  const keywords = extractKeywords(params.userMessage);
  
  window.APPFLOW_CHAT_SDK.setExtraInfo({
    keywords: keywords,
    messageLength: params.userMessage.length,
    sendTime: Date.now(),
  });
});

Example 3: Asynchronous preprocessing

window.APPFLOW_CHAT_SDK.onBeforeSend(async (params) => {
  // Call a backend API to get the user context.
  const response = await fetch('/api/user/context');
  const userContext = await response.json();
  
  // Set extra parameters.
  window.APPFLOW_CHAT_SDK.setExtraInfo({
    userContext: userContext,
    processedAt: Date.now(),
  });
}, { async: true });

Parameters on success

Parameters on failure

Synchronous mode (default)

In synchronous mode, the handler executes and does not block subsequent operations. Even if the handler returns a Promise, the SDK does not wait for it to resolve. This mode is suitable for non-blocking tasks like logging, analytics tracking, or UI updates.

// Synchronous mode
window.APPFLOW_CHAT_SDK.onAfterSend((params) => {
  if (params.success) {
    console.log('Message sent successfully');
    console.log('AI reply:', params.assistantContent);
  } else {
    console.error('Message sending failed:', params.error.message);
  }
});

Asynchronous mode (async: true)

In asynchronous mode, if the handler function returns a Promise, the SDK waits for the Promise to resolve. This is ideal for scenarios requiring asynchronous operations after a reply is complete, such as data persistence or subsequent API calls.

// Asynchronous mode
window.APPFLOW_CHAT_SDK.onAfterSend(async (params) => {
  if (params.success) {
    // Asynchronously save the conversation history
    await saveConversation({
      question: params.userMessage,
      answer: params.assistantContent,
      references: params.assistantReferences,
    });
  }
}, { async: true });

Example 1: Basic logging

window.APPFLOW_CHAT_SDK.onAfterSend((params) => {
  const timestamp = new Date().toISOString();
  
  if (params.success) {
    console.log(`[${timestamp}] Conversation completed`);
    console.log(`  User: ${params.userMessage}`);
    console.log(`  AI: ${params.assistantContent.substring(0, 100)}...`);
    console.log(`  Reference count: ${params.assistantReferences.length}`);
  } else {
    console.error(`[${timestamp}] Conversation failed`);
    console.error(`  User: ${params.userMessage}`);
    console.error(`  Error: [${params.error.code}] ${params.error.message}`);
  }
});

Example 2: Analytics tracking

window.APPFLOW_CHAT_SDK.onAfterSend((params) => {
  // Send analytics event
  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(),
  });
});

Example 3: Conversation history persistence (asynchronous)

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('Failed to save conversation history:', error);
  }
}, { async: true });