Overview
Provide cloud development AI access capability for quick integration with large models and Agent.
Basic Usage Example
Publishable Key can be generated by going to Cloud Development Platform/API Key Configuration
Type Declaration
function ai(): AI;
Return value
Return the newly created AI instance.
import cloudbase from "@cloudbase/js-sdk";
// Initialize it.
const app = cloudbase.init({
env: "your-env-id", // Replace with your environment ID
region: "ap-shanghai", // Region, defaults to Shanghai
accessKey: "", // Fill in the generated Publishable Key
});
// If accessKey is filled in, this step is not required
await app.auth.signInAnonymously();
const ai = app.ai();
Basic text generation example
async function generateText() {
const model = ai.createModel("hunyuan-exp");
const result = await model.generateText({
model: "hunyuan-lite",
messages: [{ role: "user", content: "hello, please introduce Li Bai" }],
});
console.log("Generated text:", result.text);
console.log("token consumption:", result.usage);
}
Streaming text generation example
async function streamText() {
const model = ai.createModel("hunyuan-exp");
const result = await model.streamText({
model: "hunyuan-lite",
messages: [{ role: "user", content: "1+1 equals how many" }],
});
for await (let chunk of result.textStream) {
console.log("Received text chunk:", chunk);
}
}
// Agent dialogue example
async function chatWithAgent() {
const res = await ai.bot.sendMessage({
botId: "botId-xxx",
msg: "Hello, please introduce yourself"
history: [],
});
for await (let text of res.textStream) {
console.log("Agent reply:", text);
}
}
AI
Class for creating AI models.
createModel
function createModel(model: string): ChatModel;
Create the specified AI model.
-Create a new AI model instance -Return a model instance implemented the ChatModel abstract class -The instance provides AI text generation capabilities.
参数
model
string
Model identifier, for example 'hunyuan-exp', 'hunyuan-lite'
返回
ChatModel
ChatModel
A model instance implemented the ChatModel abstract class, providing AI text generation capabilities
示例
Create a Hunyuan trial version model
const model = ai.createModel("hunyuan-exp");
Create a Hunyuan lightweight model
const liteModel = ai.createModel("hunyuan-lite");
Create multiple model instances for different scenarios
const expModel = ai.createModel("hunyuan-exp"); // Trial version, fully functional
const liteModel = ai.createModel("hunyuan-lite"); // Lite version, fast response
const proModel = ai.createModel("hunyuan-pro"); // Pro Edition, stronger performance
// Choose different models as needed
async function generateWithModel(scenario: string, content: string) {
let selectedModel;
switch (scenario) {
case "creative":
selectedModel = expModel;
break;
case "quick":
selectedModel = liteModel;
break;
case "professional":
selectedModel = proModel;
break;
default:
selectedModel = liteModel;
}
const result = await selectedModel.generateText({
model: scenario,
messages: [{ role: "user", content: content }],
});
return result.text;
}
bot
An instance of the Bot class is mounted, with a collection of methods to interact with the Agent. For details, see the Bot class detailed documentation.
Usage Example
const agentList = await ai.bot.list({ pageNumber: 1, pageSize: 10 });
registerFunctionTool
function registerFunctionTool(functionTool: FunctionTool): void;
Register function tools. When performing large model invocation, you can inform the large model of available function tools. When the large model's response is resolved to a tool call, it will automatically call the corresponding function tool.
参数
functionTool
FunctionTool
Function tool definition to register
返回
void
undefined
no return value
示例
// Define a tool to get weather
const getWeatherTool = {
name: "get_weather",
description: "Return the weather information of a certain city. Sample call: get_weather({city: 'Beijing'})",
fn: ({ city }) => `${city} weather: clear and crisp autumn air.`
parameters: {
type: "object",
properties: {
city: {
type: "string",
description: "City to query"
},
},
required: ["city"],
},
};
// Registration tool
ai.registerFunctionTool(getWeatherTool);
Use tools to perform dialogue
const model = ai.createModel("hunyuan-exp");
const result = await model.generateText({
model: "hunyuan-turbo",
tools: [getWeatherTool],
messages: [
{
role: "user",
how can i assist you with the weather in Beijing?
},
],
});
console.log(result.text);
// Multi-tool integrated system
class ToolIntegrationSystem {
private registeredTools: Map<string, FunctionTool> = new Map();
// Register multiple tools
registerTools(tools: FunctionTool[]): void {
tools.forEach((tool) => {
ai.registerFunctionTool(tool);
this.registeredTools.set(tool.name, tool);
console.log(`✓ Tool registered successfully: ${tool.name}`);
});
}
// Get all available tools
getAvailableTools(): FunctionTool[] {
return Array.from(this.registeredTools.values());
}
// Intelligent dialogue assistant
async smartAssistant(question: string): Promise<string> {
const model = ai.createModel("hunyuan-exp");
const result = await model.generateText({
model: "hunyuan-turbo",
tools: this.getAvailableTools(),
messages: [
{
role: "user",
content: question,
},
],
});
return result.text;
}
// Tool usage statistics
getToolUsageStats(): Map<string, number> {
const stats = new Map<string, number>();
// In practical applications, here you can record tool call count
return stats;
}
}
Define multiple tools
const tools = [
{
name: "get_weather",
description: "Get city weather info"
fn: ({ city }) => `${city} weather: sunny, 25℃`
parameters: {
type: "object",
properties: { city: { type: "string", description: "city name" } },
required: ["city"],
},
},
{
name: "calculate",
description: "Execute math calculations"
fn: ({ expression }) => `Computed result: ${eval(expression)}`
parameters: {
type: "object",
properties: { expression: { type: "string", description: "mathematical expression" } },
required: ["expression"],
},
},
{
name: "search_info",
description: "Search information"
fn: ({ keyword }) => `Search result: about ${keyword} information`
parameters: {
type: "object",
properties: { keyword: { type: "string", description: "search keyword" } },
required: ["keyword"],
},
},
];
Usage Example
const toolSystem = new ToolIntegrationSystem();
toolSystem.registerTools(tools);
// Intelligent dialogue
const answer = await toolSystem.smartAssistant(
Calculate the result of 15*8+20 and tell me the weather in Beijing.
);
console.log("Assistant response:", answer);
// Dynamic tool management system
class DynamicToolManager {
private toolRegistry: Map<string, FunctionTool> = new Map();
// Dynamic registration tool
registerTool(tool: FunctionTool): void {
ai.registerFunctionTool(tool);
this.toolRegistry.set(tool.name, tool);
console.log(`Tool registration: ${tool.name}`);
}
// Dynamically uninstall tool
unregisterTool(toolName: string): boolean {
if (this.toolRegistry.has(toolName)) {
this.toolRegistry.delete(toolName);
console.log(`Tool uninstallation: ${toolName}`);
return true;
}
return false;
}
Dynamically select a tool based on context
async contextualAssistant(
context: string,
question: string
): Promise<string> {
const relevantTools = this.selectRelevantTools(context, question);
const model = ai.createModel("hunyuan-exp");
const result = await model.generateText({
model: "hunyuan-turbo",
tools: relevantTools,
messages: [
{
role: "system",
content: `Current context: ${context}`,
},
{
role: "user",
content: question,
},
],
});
return result.text;
}
Select relevant tools based on context
private selectRelevantTools(
context: string,
question: string
): FunctionTool[] {
const tools = Array.from(this.toolRegistry.values());
// Simple keyword matching algorithm
const keywords = [...context.split(" "), ...question.split(" ")];
return tools.filter((tool) => {
return keywords.some((keyword) =>
tool.description.toLowerCase().includes(keyword.toLowerCase())
);
});
}
// Hot update tool
updateTool(toolName: string, updatedTool: FunctionTool): boolean {
if (this.toolRegistry.has(toolName)) {
this.unregisterTool(toolName);
this.registerTool(updatedTool);
console.log(`Tool update: ${toolName}`);
return true;
}
return false;
}
// Get the tool list
listTools(): string[] {
return Array.from(this.toolRegistry.keys());
}
}
Usage Example
const toolManager = new DynamicToolManager();
// Register initial tool
toolManager.registerTool({
name: "weather",
description: "Get weather info"
fn: ({ city }) => `${city} weather: sunny`
parameters: {
type: "object",
properties: { city: { type: "string" } },
required: ["city"],
},
});
// Dynamically add a new tool
toolManager.registerTool({
name: "translate",
description: "Translate text"
fn: ({ text, to }) => `${text} translated to ${to}: example translation result`,
parameters: {
type: "object",
properties: {
text: { type: "string" },
to: { type: "string" },
},
required: ["text", "to"],
},
});
Context-aware dialogue
const answer = await toolManager.contextualAssistant(
weather and translation-related issues
Translate 'Hello' into English and tell me the weather in Shanghai.
);
console.log("Intelligent response:", answer);
// View available tools
console.log("Available tools:", toolManager.listTools());
ChatModel
This abstract class describes the interface provided by the AI Model Class.
generateText
function generateText(data: BaseChatModelInput): Promise<{
rawResponses: Array<unknown>;
text: string;
messages: Array<ChatModelMessage>;
usage: Usage;
error?: unknown;
}>;
Call the large model to generate text.
-Send message to the large model and obtain the generated text response -Support fully managed dialogue context -Return detailed invocation information and token consumption statistics
参数
data
BaseChatModelInput
Input parameters for the large model, including model configuration and message content
返回
Promise
object
Response result of text generated by the large model
示例
const model = ai.createModel("hunyuan-exp");
const result = await model.generateText({
model: "hunyuan-lite",
messages: [{ role: "user", content: "hello, please introduce Li Bai" }],
});
console.log("Generated text:", result.text);
console.log("token consumption:", result.usage);
const model = ai.createModel("hunyuan-exp");
// Multi-round dialogue example
const messages = [
hello, I want to learn about ancient Chinese literature
{
role: "assistant",
content:
Ancient Chinese literature has a long history, from the Book of Songs and the Songs of Chu to Tang poetry and Song lyrics, all embodying rich cultural significance.
},
{ role: "user", content: "Can you introduce the characteristics of Tang poetry?" },
];
const result = await model.generateText({
model: "hunyuan-lite",
messages: messages,
temperature: 0.7,
topP: 0.9,
});
console.log("Tang poetry introduction:", result.text);
// Register weather query tool
ai.registerFunctionTool({
name: "get_weather",
description: "Query city weather info"
fn: ({ city }) => `${city} weather: clear, 25℃`
parameters: {
type: "object",
properties: {
city: {
type: "string",
description: "City name to query"
},
},
required: ["city"],
},
});
const model = ai.createModel("hunyuan-exp");
const result = await model.generateText({
model: "hunyuan-lite",
messages: [{ role: "user", content: "What is the weather like in Beijing?" }],
tools: [getWeatherTool],
toolChoice: "auto",
});
console.log("large model response:", result.text);
streamText
function streamText(data: BaseChatModelInput): Promise<StreamTextResult>;
Call the large model to generate text with streaming.
-When calling with streaming, the generated text and other response data are returned via SSE. This API's returned value encapsulates SSE at different levels, allowing developers to obtain the text stream and complete data stream according to actual needs. -Call the large model in streaming method to generate text, supporting real-time access to incremental content.
参数
data
BaseChatModelInput
Input parameters for the large model, including model configuration and message content
返回
Promise
StreamTextResult
Streaming text generation result, including text stream and data stream
示例
const model = ai.createModel("hunyuan-exp");
const result = await model.streamText({
model: "hunyuan-lite",
messages: [{ role: "user", content: "hello, please introduce Li Bai" }],
});
// Obtain text streams
for await (let chunk of result.textStream) {
console.log("Received text chunk:", chunk);
}
// 1
// Add
// 1
// Result
// Yes
// 2
// .
// Obtain data streams
for await (let data of result.dataStream) {
console.log("Received data chunk:", data);
}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
Display streaming content on the web page in real time
async function displayStreamingText(question: string) {
const model = ai.createModel("hunyuan-exp");
const result = await model.streamText({
model: "hunyuan-lite",
messages: [{ role: "user", content: question }],
});
const outputElement = document.getElementById("output");
outputElement.innerHTML = "";
for await (let chunk of result.textStream) {
outputElement.innerHTML += chunk;
// Scroll to the latest content
outputElement.scrollTop = outputElement.scrollHeight;
}
}
Usage Example
displayStreamingText("Please introduce the development history of Tang poetry in detail");
// Monitor streaming generation progress
async function monitorStreamProgress(question: string) {
const model = ai.createModel("hunyuan-exp");
const result = await model.streamText({
model: "hunyuan-lite",
messages: [{ role: "user", content: question }],
});
let totalChunks = 0;
let startTime = Date.now();
for await (let chunk of result.textStream) {
totalChunks++;
console.log(`Text chunk ${totalChunks}: ${chunk}`);
}
const endTime = Date.now();
console.log(
`Generation completed, ${totalChunks} text chunks, duration ${
endTime - startTime
}ms`
);
// Obtain the complete message and token statistics
const messages = await result.messages;
const usage = await result.usage;
console.log("Complete dialogue:", messages);
console.log("Token consumption:", usage);
}
Bot
Class for interacting with Agent.
get
function get(props: { botId: string }): Promise<BotInfo>;
Get info of a certain Agent.
-Get detailed Agent info based on Agent ID -Return the complete information of Agent, including basic configuration, welcome message and avatar.
参数
props
object
Parameters for retrieving Agent Information
返回
Promise
BotInfo
Detailed information of the Agent
示例
const res = await ai.bot.get({ botId: "botId-xxx" });
console.log("Agent Information:", res);
Load Agent configuration during application startup
async function initializeAgent(botId: string) {
try {
const agentInfo = await ai.bot.get({ botId });
// Set UI
document.title = `${agentInfo.name} - AI assistant`;
// Display welcome message
const welcomeElement = document.getElementById("welcome");
welcomeElement.innerHTML = `
<div class="agent-header">
<img src="${agentInfo.avatar}" alt="${agentInfo.name}" class="avatar" />
<h2>${agentInfo.name}</h2>
<p>${agentInfo.introduction}</p>
</div>
`;
// Set chat background
if (agentInfo.background) {
document.body.style.backgroundImage = `url(${agentInfo.background})`;
}
return agentInfo;
} catch (error) {
console.error("Failed to load Agent configuration:", error);
throw error;
}
}
Usage Example
initializeAgent("bot-27973647");
Manage multiple Agent configurations
class AgentManager {
private agents: Map<string, BotInfo> = new Map();
async loadAgent(botId: string) {
if (this.agents.has(botId)) {
return this.agents.get(botId);
}
const agentInfo = await ai.bot.get({ botId });
this.agents.set(botId, agentInfo);
return agentInfo;
}
getAgentList() {
return Array.from(this.agents.values());
}
async switchAgent(botId: string) {
const agentInfo = await this.loadAgent(botId);
// Refresh interface display
this.updateUI(agentInfo);
return agentInfo;
}
private updateUI(agentInfo: BotInfo) {
// Update interface element
console.log("Switch to Agent:", agentInfo.name);
}
}
Usage Example
const agentManager = new AgentManager();
await agentManager.loadAgent("bot-27973647");
await agentManager.loadAgent("bot-27973648");
list
function list(props: {
name: string;
introduction: string;
information: string;
enable: boolean;
pageSize: number;
pageNumber: number;
}): Promise<AgentListResult>;
Batch get info of multiple Agents.
-Query and filter the available Agent list -Support paging query and conditional filtering -Return the basic info and configuration detail of Agent -Suitable for building applications like Agent selector and management interface.
参数
props
object
Parameters for querying the Agent list
返回
Promise
AgentListResult
Agent list query result
示例
const agentList = await ai.bot.list({
pageNumber: 1,
pageSize: 10,
name: "",
enable: true,
information: "",
introduction: "",
});
console.log("Total Agents:", agentList.total);
console.log("Agent list:", agentList.botList);
// Filter Agents based on conditions
async function searchAgents(keyword: string, page: number = 1) {
const result = await ai.bot.list({
pageNumber: page,
pageSize: 20,
name: keyword,
enable: true,
information: keyword,
introduction: keyword,
});
console.log(`Found ${result.total} matching Agents`);
result.botList.forEach((agent) => {
console.log(`- ${agent.name}: ${agent.introduction}`);
});
return result;
}
Usage Example
await searchAgents("translation"); // Search for Agents related to translation
await searchAgents("customer service", 2); // Search for Agents related to customer service, second page
// Build the Agent picker interface
class AgentSelector {
private currentPage: number = 1;
private pageSize: number = 12;
async loadAgents(keyword: string = "") {
const result = await ai.bot.list({
pageNumber: this.currentPage,
pageSize: this.pageSize,
name: keyword,
enable: true,
information: keyword,
introduction: keyword,
});
this.displayAgents(result.botList);
this.updatePagination(result.total);
return result;
}
private displayAgents(agents: any[]) {
const container = document.getElementById("agent-list");
container.innerHTML = "";
agents.forEach((agent) => {
const agentCard = document.createElement("div");
agentCard.className = "agent-card";
agentCard.innerHTML = `
<img src="${agent.avatar}" alt="${agent.name}" class="agent-avatar" />
<div class="agent-info">
<h3>${agent.name}</h3>
<p>${agent.introduction}</p>
<button onclick="selectAgent('${agent.botId}')">Select</button>
</div>
`;
container.appendChild(agentCard);
});
}
private updatePagination(total: number) {
const pagination = document.getElementById("pagination");
const totalPages = Math.ceil(total / this.pageSize);
pagination.innerHTML = `
<button onclick="prevPage()" ${
this.currentPage <= 1 ? "disabled" : ""
}>Previous Page</button>
<span>Page ${this.currentPage} of ${totalPages}</span>
<button onclick="nextPage()" ${
this.currentPage >= totalPages ? "disabled" : ""
}>Next Page</button>
`;
}
async nextPage() {
this.currentPage++;
await this.loadAgents();
}
async prevPage() {
if (this.currentPage > 1) {
this.currentPage--;
await this.loadAgents();
}
}
selectAgent(botId: string) {
console.log("Selected Agent ID:", botId);
// Start dialogue with the selected Agent
this.startChat(botId);
}
private startChat(botId: string) {
// Implement the logic to start dialogue with the Agent
console.log("Start dialogue with the Agent:", botId);
}
}
Usage Example
const selector = new AgentSelector();
await selector.loadAgents(); // Load the first page of agents
// Search for a specific type of Agent
await selector.loadAgents("writing assistant");
sendMessage
function sendMessage(props: {
botId: string;
msg: string;
history: Array<{
role: string;
content: string;
}>;
}): Promise<StreamResult>;
Start dialogue with the Agent.
-The response will be returned via SSE. This API's returned value encapsulates SSE at different levels, allowing developers to obtain text streams and complete data streams based on actual needs. -Support multi-round dialogue context management
- Return streaming response and support real-time access to Agent reply -Suitable for building chatbots, smart assistants and other applications.
参数
props
object
Parameters for sending messages
返回
Promise
StreamResult
Streaming dialogue result, including text stream and data stream
示例
const res = await ai.bot.sendMessage({
botId: "botId-xxx",
history: [{ content: "You are Li Bai.", role: "user" }],
msg: "Hello",
});
// Obtain text streams
for await (let text of res.textStream) {
console.log("Agent reply:", text);
}
// Retrieve data streams
for await (let data of res.dataStream) {
console.log("Details:", data);
}
// Multi-round dialogue example
class ChatSession {
private history: Array<{ role: string; content: string }> = [];
async sendMessage(botId: string, message: string) {
const res = await ai.bot.sendMessage({
botId: botId,
history: this.history,
msg: message,
});
let fullResponse = "";
// Display replies in real time
for await (let chunk of res.textStream) {
fullResponse += chunk;
this.updateDisplay(fullResponse);
}
// Log chat history
this.history.push({ role: "user", content: message });
this.history.push({ role: "assistant", content: fullResponse });
return fullResponse;
}
private updateDisplay(text: string) {
const chatArea = document.getElementById("chat-area");
chatArea.innerHTML = text;
chatArea.scrollTop = chatArea.scrollHeight;
}
clearHistory() {
this.history = [];
}
getHistory() {
return this.history;
}
}
Usage Example
const chatSession = new ChatSession();
await chatSession.sendMessage("botId-xxx", "Hello, please introduce yourself");
await chatSession.sendMessage("botId-xxx", "Can you help me write a poem?");
// Build a real-time chat app
class ChatApp {
private botId: string;
private conversationId: string;
constructor(botId: string) {
this.botId = botId;
this.setupEventListeners();
}
private setupEventListeners() {
const sendBtn = document.getElementById("send-btn");
const input = document.getElementById("message-input") as HTMLInputElement;
sendBtn.addEventListener("click", () => {
this.sendMessage(input.value);
input.value = "";
});
input.addEventListener("keypress", (e) => {
if (e.key === "Enter") {
this.sendMessage(input.value);
input.value = "";
}
});
}
async sendMessage(message: string) {
if (!message.trim()) return;
// Display user message
this.displayMessage("user", message);
try {
const res = await ai.bot.sendMessage({
botId: this.botId,
history: this.getChatHistory(),
msg: message,
});
// Display streaming replies
const assistantDiv = this.displayMessage("assistant", "");
for await (let chunk of res.textStream) {
assistantDiv.innerHTML += chunk;
assistantDiv.scrollIntoView({ behavior: "smooth" });
}
} catch (error) {
this.displayMessage("error", "Failed to send message: " + error.message);
}
}
private displayMessage(role: string, content: string): HTMLDivElement {
const chatContainer = document.getElementById("chat-container");
const messageDiv = document.createElement("div");
messageDiv.className = `message ${role}`;
messageDiv.innerHTML = content;
chatContainer.appendChild(messageDiv);
chatContainer.scrollTop = chatContainer.scrollHeight;
return messageDiv;
}
private getChatHistory() {
const messages = document.querySelectorAll(".message");
const history = [];
for (let message of messages) {
const role = message.classList.contains("user") ? "user" : "assistant";
const content = message.innerHTML;
history.push({ role, content });
}
return history;
}
}
Usage Example
const chatApp = new ChatApp("botId-xxx");
getChatRecords
function getChatRecords(props: {
botId: string;
sort: string;
pageSize: number;
pageNumber: number;
}): Promise<ChatRecordsResult>;
Retrieve chat record.
- Retrieve historical chat records of the specified Agent
- Support paging query and sort
- Return complete chat history
- Suitable to build chat history view function
参数
props
object
Parameters for chat record retrieval
返回
Promise
ChatRecordsResult
Chat record query result
示例
const records = await ai.bot.getChatRecords({
botId: "botId-xxx",
pageNumber: 1,
pageSize: 10,
sort: "asc",
});
console.log("Total Record Count:", records.total);
console.log("Record List:", records.recordList);
// Query chat records with paging
class ChatHistoryManager {
private botId: string;
private currentPage: number = 1;
private pageSize: number = 20;
constructor(botId: string) {
this.botId = botId;
}
async loadPage(pageNumber: number) {
const records = await ai.bot.getChatRecords({
botId: this.botId,
pageNumber: pageNumber,
pageSize: this.pageSize,
sort: "desc", // By Time in descending order
});
this.currentPage = pageNumber;
return records;
}
async nextPage() {
return this.loadPage(this.currentPage + 1);
}
async previousPage() {
if (this.currentPage > 1) {
return this.loadPage(this.currentPage - 1);
}
return null;
}
getTotalPages(totalRecords: number) {
return Math.ceil(totalRecords / this.pageSize);
}
}
Usage Example
const historyManager = new ChatHistoryManager("botId-xxx");
const firstPage = await historyManager.loadPage(1);
console.log("Page 1 Records:", firstPage.recordList);
const secondPage = await historyManager.nextPage();
console.log("Page 2 Records:", secondPage.recordList);
// Build chat history view interface
class ChatHistoryViewer {
private botId: string;
constructor(botId: string) {
this.botId = botId;
this.setupUI();
}
private setupUI() {
const historyContainer = document.getElementById("history-container");
const prevBtn = document.getElementById("prev-btn");
const nextBtn = document.getElementById("next-btn");
const pageInfo = document.getElementById("page-info");
prevBtn.addEventListener("click", () => this.previousPage());
nextBtn.addEventListener("click", () => this.nextPage());
}
async loadHistory(pageNumber: number = 1) {
const records = await ai.bot.getChatRecords({
botId: this.botId,
pageNumber: pageNumber,
pageSize: 10,
sort: "desc",
});
this.displayRecords(records.recordList);
this.updatePageInfo(pageNumber, records.total);
}
private displayRecords(records: any[]) {
const container = document.getElementById("records-container");
container.innerHTML = "";
records.forEach((record) => {
const recordDiv = document.createElement("div");
recordDiv.className = "chat-record";
recordDiv.innerHTML = `
<div class="record-header">
<span class="role">${record.role}</span>
<span class="time">${record.createTime}</span>
</div>
<div class="content">${record.content}</div>
`;
container.appendChild(recordDiv);
});
}
private updatePageInfo(currentPage: number, total: number) {
const pageInfo = document.getElementById("page-info");
const totalPages = Math.ceil(total / 10);
pageInfo.textContent = `Page ${currentPage} of ${totalPages}, total ${total} records`;
}
async nextPage() {
const currentPage = parseInt(
document.getElementById("page-info").textContent.match(/Page (\d+)/)[1]
);
await this.loadHistory(currentPage + 1);
}
async previousPage() {
const currentPage = parseInt(
document.getElementById("page-info").textContent.match(/Page (\d+)/)[1]
);
if (currentPage > 1) {
await this.loadHistory(currentPage - 1);
}
}
}
Usage Example
const historyViewer = new ChatHistoryViewer("botId-xxx");
await historyViewer.loadHistory(1);
sendFeedback
function sendFeedback(props: {
userFeedback: IUserFeedback;
botId: string;
}): Promise<void>;
Send feedback information for a chat record.
-Evaluate and provide feedback for the specified chat record.
- Support multiple feedback methods such as score, comment, and tag. -Help improve Agent response quality -Suitable for building user feedback systems
参数
props
object
Parameters for sending feedback
返回
Promise
void
no return value
示例
const res = await ai.bot.sendFeedback({
userFeedback: {
botId: "botId-xxx",
recordId: "recordId-xxx",
comment: "super",
rating: 5,
tags: ["elegant"],
aiAnswer: "falling petals",
input: "Give me an idiom",
type: "upvote",
},
botId: "botId-xxx",
});
console.log("Feedback sent successfully");
// Build a user feedback system
class FeedbackSystem {
private botId: string;
constructor(botId: string) {
this.botId = botId;
this.setupFeedbackUI();
}
private setupFeedbackUI() {
const feedbackButtons = document.querySelectorAll(".feedback-btn");
feedbackButtons.forEach((button) => {
button.addEventListener("click", (e) => {
const recordId = e.target.dataset.recordId;
const type = e.target.dataset.type; // upvote or downvote
this.showFeedbackDialog(recordId, type);
});
});
}
private showFeedbackDialog(recordId: string, type: string) {
const dialog = document.getElementById("feedback-dialog");
const submitBtn = document.getElementById("submit-feedback");
const ratingInput = document.getElementById("rating") as HTMLInputElement;
const commentInput = document.getElementById(
"comment"
) as HTMLTextAreaElement;
const tagsInput = document.getElementById("tags") as HTMLInputElement;
dialog.style.display = "block";
submitBtn.onclick = async () => {
await this.submitFeedback(recordId, type, {
rating: parseInt(ratingInput.value),
comment: commentInput.value,
tags: tagsInput.value.split(",").map((tag) => tag.trim()),
});
dialog.style.display = "none";
};
}
async submitFeedback(
recordId: string,
type: string,
feedback: {
rating: number;
comment: string;
tags: string[];
}
) {
try {
await ai.bot.sendFeedback({
userFeedback: {
botId: this.botId,
recordId: recordId,
comment: feedback.comment,
rating: feedback.rating,
tags: feedback.tags,
aiAnswer: this.getCurrentAnswer(),
input: this.getCurrentQuestion(),
type: type,
},
botId: this.botId,
});
this.showSuccessMessage("Appreciate your feedback.");
} catch (error) {
this.showErrorMessage("Feedback sending failure: " + error.message);
}
}
private getCurrentAnswer(): string {
// Get the answer content of the current conversation
const answerElement = document.querySelector(
".assistant-message:last-child"
);
return answerElement?.textContent || "";
}
private getCurrentQuestion(): string {
// Get the issue content of the current conversation
const questionElement = document.querySelector(".user-message:last-child");
return questionElement?.textContent || "";
}
private showSuccessMessage(message: string) {
const notification = document.createElement("div");
notification.className = "notification success";
notification.textContent = message;
document.body.appendChild(notification);
setTimeout(() => notification.remove(), 3000);
}
private showErrorMessage(message: string) {
const notification = document.createElement("div");
notification.className = "notification error";
notification.textContent = message;
document.body.appendChild(notification);
setTimeout(() => notification.remove(), 5000);
}
}
Usage Example
const feedbackSystem = new FeedbackSystem("botId-xxx");
// Batch-process user feedback
class BatchFeedbackProcessor {
private botId: string;
private feedbackQueue: Array<{
recordId: string;
type: string;
rating: number;
comment: string;
tags: string[];
}> = [];
constructor(botId: string) {
this.botId = botId;
this.startProcessing();
}
addFeedback(
recordId: string,
type: string,
rating: number,
comment: string,
tags: string[]
) {
this.feedbackQueue.push({ recordId, type, rating, comment, tags });
}
private async startProcessing() {
setInterval(async () => {
if (this.feedbackQueue.length > 0) {
await this.processBatch();
}
}, 5000); // Process once every 5 seconds
}
private async processBatch() {
const batch = this.feedbackQueue.splice(0, 10); // Process up to 10 feedback items in each process
const promises = batch.map((feedback) => {
return ai.bot.sendFeedback({
userFeedback: {
botId: this.botId,
recordId: feedback.recordId,
comment: feedback.comment,
rating: feedback.rating,
tags: feedback.tags,
aiAnswer: "", // Get according to the actual situation
input: "", // Get according to the actual situation
type: feedback.type,
},
botId: this.botId,
});
});
try {
await Promise.all(promises);
console.log(`Successful handling of ${batch.length} feedbacks`);
} catch (error) {
console.error("Batch processing feedback failed:", error);
// Rejoin failed feedback to the queue
this.feedbackQueue.unshift(...batch);
}
}
getQueueSize() {
return this.feedbackQueue.length;
}
}
Usage Example
const feedbackProcessor = new BatchFeedbackProcessor("botId-xxx");
// Add multiple feedback
feedbackProcessor.addFeedback("record-1", "upvote", 5, "Great answer", [
accurate
"Detailed"
]);
feedbackProcessor.addFeedback("record-2", "downvote", 2, "Insufficiently accurate response", [
inaccurate
]);
console.log("Current queue size:", feedbackProcessor.getQueueSize());
getFeedback
function getFeedback(props: {
botId: string;
type: string;
sender: string;
senderFilter: string;
minRating: number;
maxRating: number;
from: number;
to: number;
pageSize: number;
pageNumber: number;
}): Promise<FeedbackResult>;
Retrieve existing feedback information.
-Query specified Agent user feedback records -Support various filter conditions: time range, score range, user filtering, etc.
- Return paginated feedback results and statistical information -Suitable for building feedback analytics and management systems
参数
props
object
Parameters for querying feedback information
返回
Promise
FeedbackResult
Feedback query result
示例
const res = await ai.bot.getFeedback({
botId: "botId-xxx",
from: 0,
to: 0,
maxRating: 4,
minRating: 3,
pageNumber: 1,
pageSize: 10,
sender: "user-a",
senderFilter: "include",
type: "upvote",
});
console.log("Total Feedback:", res.total);
console.log("Feedback List:", res.feedbackList);
// Build a feedback analysis system
class FeedbackAnalyzer {
private botId: string;
constructor(botId: string) {
this.botId = botId;
}
async analyzeFeedback(timeRange: { from: number; to: number }) {
const feedback = await ai.bot.getFeedback({
botId: this.botId,
from: timeRange.from,
to: timeRange.to,
minRating: 1,
maxRating: 5,
pageNumber: 1,
pageSize: 1000, // Get enough data to analyze
sender: "",
senderFilter: "include",
type: "",
});
return this.generateReport(feedback.feedbackList);
}
private generateReport(feedbackList: any[]) {
const report = {
total: feedbackList.length,
upvotes: feedbackList.filter((f) => f.type === "upvote").length,
downvotes: feedbackList.filter((f) => f.type === "downvote").length,
averageRating: this.calculateAverageRating(feedbackList),
commonTags: this.getCommonTags(feedbackList),
ratingDistribution: this.getRatingDistribution(feedbackList),
topComments: this.getTopComments(feedbackList),
};
return report;
}
private calculateAverageRating(feedbackList: any[]): number {
const ratings = feedbackList.map((f) => f.rating).filter((r) => r > 0);
return ratings.length > 0
? ratings.reduce((a, b) => a + b, 0) / ratings.length
: 0;
}
private getCommonTags(feedbackList: any[]): string[] {
const tagCounts = new Map<string, number>();
feedbackList.forEach((feedback) => {
feedback.tags?.forEach((tag) => {
tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
});
});
return Array.from(tagCounts.entries())
.sort((a, b) => b[1] - a[1])
.slice(0, 10)
.map((entry) => entry[0]);
}
private getRatingDistribution(feedbackList: any[]): Record<number, number> {
const distribution = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
feedbackList.forEach((feedback) => {
if (feedback.rating >= 1 && feedback.rating <= 5) {
distribution[feedback.rating]++;
}
});
return distribution;
}
private getTopComments(feedbackList: any[]): any[] {
return feedbackList
.filter((f) => f.comment && f.comment.length > 0)
.sort((a, b) => b.rating - a.rating)
.slice(0, 5);
}
}
Usage Example
const analyzer = new FeedbackAnalyzer("botId-xxx");
const report = await analyzer.analyzeFeedback({
from: Date.now() - 7 * 24 * 60 * 60 * 1000, // Last 7 days
to: Date.now(),
});
console.log("Feedback Analysis Report:", report);
// Build a feedback management interface
class FeedbackManager {
private botId: string;
constructor(botId: string) {
this.botId = botId;
this.setupUI();
}
private setupUI() {
const filterForm = document.getElementById("feedback-filter-form");
const resultsContainer = document.getElementById("feedback-results");
const exportBtn = document.getElementById("export-feedback");
filterForm.addEventListener("submit", (e) => {
e.preventDefault();
this.loadFeedback(this.getFilterValues());
});
exportBtn.addEventListener("click", () => {
this.exportFeedback();
});
}
private getFilterValues() {
const formData = new FormData(
document.getElementById("feedback-filter-form")
);
return {
type: formData.get("type") as string,
minRating: parseInt(formData.get("minRating") as string),
maxRating: parseInt(formData.get("maxRating") as string),
from: this.parseDate(formData.get("fromDate") as string),
to: this.parseDate(formData.get("toDate") as string),
pageNumber: 1,
pageSize: 50,
};
}
private parseDate(dateString: string): number {
return dateString ? new Date(dateString).getTime() : 0;
}
async loadFeedback(filters: any) {
try {
const res = await ai.bot.getFeedback({
botId: this.botId,
...filters,
sender: "",
senderFilter: "include",
});
this.displayResults(res.feedbackList, res.total);
} catch (error) {
this.showError("Load feedback fail: " + error.message);
}
}
private displayResults(feedbackList: any[], total: number) {
const container = document.getElementById("feedback-results");
container.innerHTML = "";
const summary = document.createElement("div");
summary.className = "feedback-summary";
summary.innerHTML = `Found ${total} feedback records in total`;
container.appendChild(summary);
feedbackList.forEach((feedback) => {
const feedbackCard = this.createFeedbackCard(feedback);
container.appendChild(feedbackCard);
});
}
private createFeedbackCard(feedback: any): HTMLDivElement {
const card = document.createElement("div");
card.className = `feedback-card ${feedback.type}`;
card.innerHTML = `
<div class="feedback-header">
<span class="type ${feedback.type}">${
feedback.type === "upvote" ? "👍" : "👎"
}</span>
<span class="rating">Score: ${feedback.rating}/5</span>
<span class="time">${new Date(
feedback.createTime
).toLocaleString()}</span>
</div>
<div class="feedback-content">
<div class="question"><strong>Issue:</strong> ${feedback.input}</div>
<div class="answer"><strong>Answer:</strong> ${feedback.aiAnswer}</div>
<div class="comment"><strong>Comment:</strong> ${feedback.comment}</div>
<div class="tags"><strong>Tag:</strong> ${
feedback.tags?.join(", ") || "None"
}</div>
</div>
`;
return card;
}
private async exportFeedback() {
const res = await ai.bot.getFeedback({
botId: this.botId,
from: 0,
to: Date.now(),
minRating: 1,
maxRating: 5,
pageNumber: 1,
pageSize: 10000,
sender: "",
senderFilter: "include",
type: "",
});
const csv = this.convertToCSV(res.feedbackList);
this.downloadCSV(csv, `feedback_${this.botId}_${Date.now()}.csv`);
}
private convertToCSV(feedbackList: any[]): string {
const headers = ["Type", "score", "issue", "response", "comment", "Tag", "time"];
const rows = feedbackList.map((f) => [
f.type,
f.rating,
f.input,
f.aiAnswer,
f.comment,
f.tags?.join(";"),
new Date(f.createTime).toLocaleString(),
]);
return [headers, ...rows]
.map((row) => row.map((cell) => `"${cell}"`).join(","))
.join("\n");
}
private downloadCSV(csv: string, filename: string) {
const blob = new Blob([csv], { type: "text/csv" });
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = filename;
a.click();
URL.revokeObjectURL(url);
}
private showError(message: string) {
const errorDiv = document.createElement("div");
errorDiv.className = "error-message";
errorDiv.textContent = message;
document.getElementById("feedback-results").appendChild(errorDiv);
}
}
Usage Example
const feedbackManager = new FeedbackManager("botId-xxx");
uploadFiles
function uploadFiles(props: {
botId: string;
fileList: Array<{
fileId: string;
fileName: string;
type: "file";
}>;
}): Promise<void>;
Upload files in cloud storage to Agent for document chat.
-Support uploading files in cloud storage to the specified Agent -Files after uploading can be used for the chat feature. -Support batch uploading multiple files -Suitable for building document QA, file analysis and other applications.
参数
props
object
File upload parameters
返回
Promise
void
no return value
示例
// Upload a single file to the specified Agent
await ai.bot.uploadFiles({
botId: "botId-xxx",
fileList: [
{
fileId: "cloud://document.docx",
fileName: "document.docx",
type: "file",
},
],
});
console.log("File uploaded successfully");
// Batch upload multiple files
async function uploadAndChat(
botId: string,
files: Array<{ fileId: string; fileName: string }>
) {
// Upload documents.
await ai.bot.uploadFiles({
botId: botId,
fileList: files.map((file) => ({
...file,
type: "file" as const,
})),
});
console.log("File upload completed, start document chat");
// Chat based on the uploaded file
const res = await ai.bot.sendMessage({
botId: botId,
msg: "Please analyze the main content of these documents"
files: files.map((f) => f.fileId),
});
// Streaming output response
for await (let text of res.textStream) {
console.log(text);
}
}
Usage Example
await uploadAndChat("your-bot-id", [
{ fileId: "cloud://report.pdf", fileName: "Quarterly Report.pdf" },
{ fileId: "cloud://data.xlsx", fileName: "data table.xlsx" },
]);
// Build a document Q&A system
class DocumentQASystem {
private botId: string;
private uploadedFiles: string[] = [];
constructor(botId: string) {
this.botId = botId;
}
async uploadDocuments(files: Array<{ fileId: string; fileName: string }>) {
await ai.bot.uploadFiles({
botId: this.botId,
fileList: files.map((file) => ({
...file,
type: "file" as const,
})),
});
this.uploadedFiles.push(...files.map((f) => f.fileId));
console.log(`${files.length} files uploaded`);
}
async askQuestion(question: string): Promise<string> {
const res = await ai.bot.sendMessage({
botId: this.botId,
msg: question,
files: this.uploadedFiles,
});
let fullAnswer = "";
for await (let text of res.textStream) {
fullAnswer += text;
}
return fullAnswer;
}
async interactiveChat() {
console.log("Q&A system started, enter 'exit' to log out");
while (true) {
const question = await this.getUserInput("Please enter a question: ");
if (question.toLowerCase() === "exit") {
console.log("goodbye");
break;
}
console.log("thinking...");
const answer = await this.askQuestion(question);
console.log("Response:", answer);
console.log("---");
}
}
private getUserInput(prompt: string): Promise<string> {
return new Promise((resolve) => {
// In practical applications, here can be browser input box or command line input
const input = prompt;
resolve(input);
});
}
}
Usage Example
const qaSystem = new DocumentQASystem("doc-bot-id");
// Upload documents.
await qaSystem.uploadDocuments([
{ fileId: "cloud://manual.pdf", fileName: "Product Manual.pdf" },
{ fileId: "cloud://faq.docx", fileName: "Common Issues.docx" },
]);
// Start interactive Q&A
await qaSystem.interactiveChat();
getRecommendQuestions
function getRecommendQuestions(props: {
botId: string;
name: string;
introduction: string;
agentSetting: string;
msg: string;
history: Array<{
role: string;
content: string;
}>;
}): Promise<StreamResult>;
Get recommended issues, intelligently generate related issues based on dialogue context.
-Intelligently recommend related issues based on current conversation content and history -Support streaming return and real-time access to recommended issues -Suitable for building intelligent dialogue assistants, chatbots and other applications. -Help users discover more related topics and enhance dialogue experience
参数
props
object
Parameters for obtaining recommended questions
返回
Promise
StreamResult
Streaming results of recommended questions
示例
// Get recommended questions
const res = await ai.bot.getRecommendQuestions({
botId: "botId-xxx",
name: "smart assistant",
introduction: "I am an intelligent dialogue assistant",
agentSetting: "Professional, friendly AI assistant",
msg: "Hello, I want to learn about AI",
history: [
{ content: "Who are you", role: "user" },
{
content:
"I am a smart assistant that can help you answer various questions",
role: "assistant",
},
],
});
// Get recommended questions via streaming
for await (let question of res.textStream) {
console.log("Recommended questions:", question);
}
// Build an intelligent dialogue assistant to automatically recommend related issues
class SmartChatAssistant {
private botId: string;
private conversationHistory: Array<{ role: string; content: string }> = [];
constructor(botId: string) {
this.botId = botId;
}
async sendMessage(message: string): Promise<string> {
Add user message to history
this.conversationHistory.push({ role: "user", content: message });
// Send a message and obtain a response
const response = await ai.bot.sendMessage({
botId: this.botId,
msg: message,
history: this.conversationHistory,
});
let assistantReply = "";
for await (let text of response.textStream) {
assistantReply += text;
}
Add assistant response to history
this.conversationHistory.push({
role: "assistant",
content: assistantReply,
});
return assistantReply;
}
async getRecommendedQuestions(): Promise<string[]> {
if (this.conversationHistory.length === 0) {
return [];
}
const latestMessage =
this.conversationHistory[this.conversationHistory.length - 1].content;
const res = await ai.bot.getRecommendQuestions({
botId: this.botId,
name: "smart assistant",
introduction: "intelligent dialogue assistant"
agentSetting: "",
msg: latestMessage,
history: this.conversationHistory,
});
const questions: string[] = [];
for await (let question of res.textStream) {
questions.push(question);
}
return questions;
}
async interactiveChat() {
console.log(
The smart assistant has started. Input 'exit' to log out or input 'suggest' to get recommended questions.
);
while (true) {
const userInput = await this.getUserInput("Please enter: ");
if (userInput.toLowerCase() === "exit") {
console.log("goodbye");
break;
}
if (userInput.toLowerCase() === "suggest") {
console.log("Recommending related issues...");
const questions = await this.getRecommendedQuestions();
console.log("Recommended questions:");
questions.forEach((q, i) => console.log(`${i + 1}. ${q}`));
continue;
}
console.log("thinking...");
const reply = await this.sendMessage(userInput);
console.log("Assistant response:", reply);
// Automatically recommend related issues
console.log("\nYou may also want to learn about:");
const questions = await this.getRecommendedQuestions();
questions.slice(0, 3).forEach((q, i) => console.log(`${i + 1}. ${q}`));
console.log("---");
}
}
private getUserInput(prompt: string): Promise<string> {
return new Promise((resolve) => {
// In practical applications, here can be browser input box
const input = prompt;
resolve(input);
});
}
}
Usage Example
const assistant = new SmartChatAssistant("smart-bot-id");
await assistant.interactiveChat();
E-commerce customer service scenario recommend issue application
class EcommerceCustomerService {
private botId: string;
constructor(botId: string) {
this.botId = botId;
}
async handleCustomerQuery(
query: string
): Promise<{ answer: string; suggestions: string[] }> {
const response = await ai.bot.sendMessage({
botId: this.botId,
msg: query,
history: [],
});
let answer = "";
for await (let text of response.textStream) {
answer += text;
}
// Get related recommended questions
const recommendRes = await ai.bot.getRecommendQuestions({
botId: this.botId,
name: "E-commerce Customer Service",
introduction: "Professional E-commerce Customer Service Assistant",
agentSetting: "Focus on answering e-commerce related issues"
msg: query,
history: [
{ role: "user", content: query },
{ role: "assistant", content: answer },
],
});
const suggestions: string[] = [];
for await (let suggestion of recommendRes.textStream) {
suggestions.push(suggestion);
}
return { answer, suggestions };
}
Fix common e-commerce scenarios
async handleProductInquiry(productName: string) {
const query = `I want to learn about the product ${productName}`;
const result = await this.handleCustomerQuery(query);
console.log("Customer service response:", result.answer);
console.log("\nYou may also want to learn about:");
result.suggestions.forEach((suggestion, index) => {
console.log(`${index + 1}. ${suggestion}`);
});
return result;
}
async handleOrderInquiry(orderId: string) {
const query = `Query the state of order ${orderId}`;
const result = await this.handleCustomerQuery(query);
console.log("Order status:", result.answer);
console.log("\nRelated services:");
result.suggestions.forEach((suggestion, index) => {
console.log(`${index + 1}. ${suggestion}`);
});
return result;
}
}
Usage Example
const customerService = new EcommerceCustomerService("ecommerce-bot-id");
Handle product inquiry
await customerService.handleProductInquiry("iPhone 15");
Handle order inquiry
await customerService.handleOrderInquiry("ORD20231226001");
createConversation
function createConversation(props: {
botId: string;
title?: string;
}): Promise<IConversation>;
Create a new dialog with the Agent and establish an independent session.
-Create a new session for the specified Agent
- Support customizable dialogue titles for easy management and identification
- Each session independently stores dialogue history
- Suitable for multi-user dialogue management requirements in various scenarios
参数
props
object
Parameters for creating a dialogue
返回
Promise
IConversation
Created dialogue info
示例
Create a new dialogue session
const conversation = await ai.bot.createConversation({
botId: "botId-xxx",
title: "Technical Consulting Chat"
});
console.log("Dialogue created successfully:", conversation.conversationId);
console.log("Dialogue title:", conversation.title);
// Multi-user dialogue management system
class ConversationManager {
private botId: string;
private userConversations: Map<string, string> = new Map(); // userId -> conversationId
constructor(botId: string) {
this.botId = botId;
}
async createUserConversation(
userId: string,
title?: string
): Promise<string> {
const conversation = await ai.bot.createConversation({
botId: this.botId,
title: title || `${userId}'s dialogue`,
});
this.userConversations.set(userId, conversation.conversationId);
console.log(`Dialogue created for user ${userId}: ${conversation.conversationId}`);
return conversation.conversationId;
}
async getUserConversation(userId: string): Promise<string | null> {
return this.userConversations.get(userId) || null;
}
async sendMessageToUser(userId: string, message: string): Promise<string> {
let conversationId = await this.getUserConversation(userId);
if (!conversationId) {
conversationId = await this.createUserConversation(userId);
}
const response = await ai.bot.sendMessage({
botId: this.botId,
msg: message,
conversationId: conversationId,
});
let reply = "";
for await (let text of response.textStream) {
reply += text;
}
return reply;
}
async getConversationHistory(userId: string) {
const conversationId = await this.getUserConversation(userId);
if (!conversationId) {
return [];
}
const conversation = await ai.bot.getConversation({
botId: this.botId,
conversationId: conversationId,
});
return conversation.history || [];
}
}
Usage Example
const manager = new ConversationManager("support-bot-id");
Create dialogue for user
await manager.createUserConversation("user123", "technical support dialogue");
// Send messages.
const reply = await manager.sendMessageToUser("user123", "There is a problem with my account");
console.log("Assistant reply:", reply);
// Get chat history
const history = await manager.getConversationHistory("user123");
console.log("Dialogue history:", history);
// Multi-topic dialogue management system
class MultiTopicConversationManager {
private botId: string;
private topicConversations: Map<string, string> = new Map(); // topic -> conversationId
constructor(botId: string) {
this.botId = botId;
}
async createTopicConversation(topic: string): Promise<string> {
const conversation = await ai.bot.createConversation({
botId: this.botId,
title: `Discussion about ${topic}`,
});
this.topicConversations.set(topic, conversation.conversationId);
console.log(`Creating topic dialogue: ${topic} -> ${conversation.conversationId}`);
return conversation.conversationId;
}
async switchTopic(topic: string, message: string): Promise<string> {
let conversationId = this.topicConversations.get(topic);
if (!conversationId) {
conversationId = await this.createTopicConversation(topic);
}
const response = await ai.bot.sendMessage({
botId: this.botId,
msg: message,
conversationId: conversationId,
});
let reply = "";
for await (let text of response.textStream) {
reply += text;
}
return reply;
}
async getTopicSummary(topic: string): Promise<string> {
const conversationId = this.topicConversations.get(topic);
if (!conversationId) {
return "No dialogue log for this topic";
}
const conversation = await ai.bot.getConversation({
botId: this.botId,
conversationId: conversationId,
});
const history = conversation.history || [];
const messageCount = history.length;
const lastMessage =
history.length > 0 ? history[history.length - 1].content : "None";
return `Topic: ${topic}\nNumber of conversations: ${messageCount}\nLast message: ${lastMessage}`;
}
listTopics(): string[] {
return Array.from(this.topicConversations.keys());
}
}
Usage Example
const topicManager = new MultiTopicConversationManager("multi-topic-bot-id");
Switch between different topics in dialogue
const techReply = await topicManager.switchTopic(
technical issue
How to resolve this bug?
);
console.log("Technical issue reply:", techReply);
const businessReply = await topicManager.switchTopic(
Business cooperation
We want to discuss cooperation
);
console.log("Business cooperation reply:", businessReply);
Return to the technical issue and continue the dialogue
const techReply2 = await topicManager.switchTopic(
technical issue
Are there other solutions?
);
console.log("Technical issue continue:", techReply2);
// View topic abstract
console.log("All topics:", topicManager.listTopics());
const summary = await topicManager.getTopicSummary("technical issue");
console.log("Technical issue abstract:\n", summary);
getConversation
function getConversation(props: {
botId: string;
pageSize?: number;
pageNumber?: number;
isDefault?: boolean;
}): Promise<ConversationListResult>;
Retrieve the conversation list of the Agent, support paging query and conditional filtering.
- Query specified Agent ALL dialogue records -Support paging query, easy to manage large number of dialogues
- Filter default dialogue or ALL dialogues
- Suitable for dialogue management, view history record and other scenarios
参数
props
object
Parameters for retrieving the conversation list
返回
Promise
ConversationListResult
Conversation list query result
示例
// Get the conversation list
const result = await ai.bot.getConversation({
botId: "botId-xxx",
pageSize: 10,
pageNumber: 1,
isDefault: false,
});
console.log(`Total ${result.total} dialogues`);
result.conversations.forEach((conversation, index) => {
console.log(
`${index + 1}. ${conversation.title} (${
conversation.messageCount
} messages)`
);
});
// Dialogue management system
class ConversationManagementSystem {
private botId: string;
constructor(botId: string) {
this.botId = botId;
}
async getAllConversations(): Promise<IConversation[]> {
let allConversations: IConversation[] = [];
let pageNumber = 1;
const pageSize = 50;
while (true) {
const result = await ai.bot.getConversation({
botId: this.botId,
pageSize: pageSize,
pageNumber: pageNumber,
isDefault: false,
});
allConversations = allConversations.concat(result.conversations);
if (result.conversations.length < pageSize) {
break;
}
pageNumber++;
}
return allConversations;
}
async searchConversations(keyword: string): Promise<IConversation[]> {
const allConversations = await this.getAllConversations();
return allConversations.filter((conversation) =>
conversation.title.toLowerCase().includes(keyword.toLowerCase())
);
}
async getRecentConversations(days: number = 7): Promise<IConversation[]> {
const allConversations = await this.getAllConversations();
const cutoffDate = new Date();
cutoffDate.setDate(cutoffDate.getDate() - days);
return allConversations.filter((conversation) => {
const updateTime = new Date(conversation.updateTime);
return updateTime >= cutoffDate;
});
}
async getConversationStats(): Promise<{
total: number;
recent: number;
averageMessages: number;
}> {
const allConversations = await this.getAllConversations();
const recentConversations = await this.getRecentConversations(7);
const totalMessages = allConversations.reduce(
(sum, conv) => sum + conv.messageCount,
0
);
const averageMessages =
allConversations.length > 0 ? totalMessages / allConversations.length : 0;
return {
total: allConversations.length,
recent: recentConversations.length,
averageMessages: Math.round(averageMessages),
};
}
async exportConversationList(): Promise<string> {
const allConversations = await this.getAllConversations();
const csv = [
"Dialogue ID, Title, Creation Time, Last Update Time, Message Count"
...allConversations.map(
(conv) =>
`${conv.conversationId},"${conv.title}",${conv.createTime},${conv.updateTime},${conv.messageCount}`
),
].join("\n");
return csv;
}
}
Usage Example
const manager = new ConversationManagementSystem("management-bot-id");
// Get session statistics
const stats = await manager.getConversationStats();
console.log(`Total dialogues: ${stats.total}`);
console.log(`Dialogues in the last 7 days: ${stats.recent}`);
console.log(`Average message count: ${stats.averageMessages}`);
// Search dialogue
const searchResults = await manager.searchConversations("technology");
console.log(`Found ${searchResults.length} technology-related dialogues`);
// Export the conversation list
const csvData = await manager.exportConversationList();
console.log("Dialogue list export completed");
// Batch dialogue analysis tool
class ConversationAnalyzer {
private botId: string;
constructor(botId: string) {
this.botId = botId;
}
async analyzeConversationPatterns(): Promise<{
timeDistribution: { hour: number; count: number }[];
messageLengthStats: { avgLength: number; maxLength: number };
topicDistribution: Map<string, number>;
}> {
const allConversations = await this.getAllConversations();
// Time distribution analysis
const timeDistribution = Array.from({ length: 24 }, (_, hour) => ({
hour,
count: allConversations.filter((conv) => {
const hour = new Date(conv.createTime).getHours();
return hour === hour;
}).length,
}));
// Message length statistics
const messageLengths = allConversations.map((conv) => conv.messageCount);
const avgLength =
messageLengths.reduce((sum, len) => sum + len, 0) / messageLengths.length;
const maxLength = Math.max(...messageLengths);
// Topic distribution analysis (based on title keyword)
const topicDistribution = new Map<string, number>();
const topics = ["technology", "business", "customer service", "product", "other"];
topics.forEach((topic) => {
const count = allConversations.filter((conv) =>
conv.title.includes(topic)
).length;
topicDistribution.set(topic, count);
});
return {
timeDistribution,
messageLengthStats: { avgLength, maxLength },
topicDistribution,
};
}
async getConversationTrends(): Promise<{
dailyTrends: { date: string; count: number }[];
weeklyTrends: { week: string; count: number }[];
}> {
const allConversations = await this.getAllConversations();
// Group by date
const dailyCounts = new Map<string, number>();
allConversations.forEach((conv) => {
const date = new Date(conv.createTime).toISOString().split("T")[0];
dailyCounts.set(date, (dailyCounts.get(date) || 0) + 1);
});
const dailyTrends = Array.from(dailyCounts.entries())
.map(([date, count]) => ({
date,
count,
}))
.sort((a, b) => a.date.localeCompare(b.date));
// Group by week
const weeklyCounts = new Map<string, number>();
allConversations.forEach((conv) => {
const date = new Date(conv.createTime);
const weekStart = new Date(date);
weekStart.setDate(date.getDate() - date.getDay());
const weekKey = weekStart.toISOString().split("T")[0];
weeklyCounts.set(weekKey, (weeklyCounts.get(weekKey) || 0) + 1);
});
const weeklyTrends = Array.from(weeklyCounts.entries())
.map(([week, count]) => ({
week,
count,
}))
.sort((a, b) => a.week.localeCompare(b.week));
return { dailyTrends, weeklyTrends };
}
private async getAllConversations(): Promise<IConversation[]> {
let allConversations: IConversation[] = [];
let pageNumber = 1;
const pageSize = 100;
while (true) {
const result = await ai.bot.getConversation({
botId: this.botId,
pageSize: pageSize,
pageNumber: pageNumber,
isDefault: false,
});
allConversations = allConversations.concat(result.conversations);
if (result.conversations.length < pageSize) {
break;
}
pageNumber++;
}
return allConversations;
}
}
Usage Example
const analyzer = new ConversationAnalyzer("analytics-bot-id");
// Analyze conversation mode
const patterns = await analyzer.analyzeConversationPatterns();
console.log("Dialogue time distribution:", patterns.timeDistribution);
console.log("Message length statistics:", patterns.messageLengthStats);
console.log("Topic distribution:", patterns.topicDistribution);
// Get dialogue trend
const trends = await analyzer.getConversationTrends();
console.log("Daily trend:", trends.dailyTrends);
console.log("Weekly trend:", trends.weeklyTrends);
deleteConversation
function deleteConversation(props: {
botId: string;
conversationId: string;
}): Promise<void>;
Delete specified dialogue session and clear dialogue history.
-Delete specified dialogue session permanently -Clear all messages in the dialogue -Free up storage space, optimize system performance
- Suitable for dialogue management, data clearing and other scenarios
参数
props
object
Parameters for deleting a conversation
返回
Promise
void
Delete operation complete, no return value
示例
//Delete specified dialogue
await ai.bot.deleteConversation({
botId: "botId-xxx",
conversationId: "conv-123",
});
console.log("Dialogue deleted successfully");
// Batch dialogue cleanup tool
class ConversationCleaner {
private botId: string;
constructor(botId: string) {
this.botId = botId;
}
async deleteOldConversations(daysThreshold: number = 30): Promise<number> {
const allConversations = await this.getAllConversations();
const cutoffDate = new Date();
cutoffDate.setDate(cutoffDate.getDate() - daysThreshold);
const oldConversations = allConversations.filter((conversation) => {
const updateTime = new Date(conversation.updateTime);
return updateTime < cutoffDate;
});
console.log(
`find ${oldConversations.length} old dialogues exceeding ${daysThreshold} days`
);
//Delete old dialogues in batches
let deletedCount = 0;
for (const conversation of oldConversations) {
try {
await ai.bot.deleteConversation({
botId: this.botId,
conversationId: conversation.conversationId,
});
deletedCount++;
console.log(`Deleted conversation: ${conversation.title}`);
} catch (error) {
console.error(`Delete conversation fail: ${conversation.title}`, error);
}
}
console.log(`${deletedCount} old dialogues deleted successfully`);
return deletedCount;
}
async deleteEmptyConversations(): Promise<number> {
const allConversations = await this.getAllConversations();
const emptyConversations = allConversations.filter(
(conversation) => conversation.messageCount === 0
);
console.log(`Found ${emptyConversations.length} empty dialogues`);
let deletedCount = 0;
for (const conversation of emptyConversations) {
try {
await ai.bot.deleteConversation({
botId: this.botId,
conversationId: conversation.conversationId,
});
deletedCount++;
} catch (error) {
console.error(`Delete empty conversation fail: ${conversation.title}`, error);
}
}
console.log(`${deletedCount} empty dialogues deleted successfully`);
return deletedCount;
}
async deleteConversationsByTitle(keyword: string): Promise<number> {
const allConversations = await this.getAllConversations();
const matchingConversations = allConversations.filter((conversation) =>
conversation.title.toLowerCase().includes(keyword.toLowerCase())
);
console.log(
`Found ${matchingConversations.length} dialogues containing "${keyword}"`
);
let deletedCount = 0;
for (const conversation of matchingConversations) {
try {
await ai.bot.deleteConversation({
botId: this.botId,
conversationId: conversation.conversationId,
});
deletedCount++;
console.log(`Deleted: ${conversation.title}`);
} catch (error) {
console.error(`Delete conversation fail: ${conversation.title}`, error);
}
}
return deletedCount;
}
private async getAllConversations(): Promise<IConversation[]> {
let allConversations: IConversation[] = [];
let pageNumber = 1;
const pageSize = 100;
while (true) {
const result = await ai.bot.getConversation({
botId: this.botId,
pageSize: pageSize,
pageNumber: pageNumber,
isDefault: false,
});
allConversations = allConversations.concat(result.conversations);
if (result.conversations.length < pageSize) {
break;
}
pageNumber++;
}
return allConversations;
}
}
Usage Example
const cleaner = new ConversationCleaner("cleanup-bot-id");
//Delete old dialogues 30 days ago
const oldDeleted = await cleaner.deleteOldConversations(30);
console.log(`${oldDeleted} old dialogues cleaned up`);
//Delete empty dialogue
const emptyDeleted = await cleaner.deleteEmptyConversations();
console.log(`${emptyDeleted} empty dialogues cleaned up`);
//Delete dialogue containing specific keyword
const keywordDeleted = await cleaner.deleteConversationsByTitle("test");
console.log(`${keywordDeleted} test dialogues cleaned up`);
// User data management system
class UserDataManager {
private botId: string;
private userConversations: Map<string, string[]> = new Map(); // userId -> conversationIds
constructor(botId: string) {
this.botId = botId;
}
async deleteUserConversations(userId: string): Promise<number> {
const userConversationIds = this.userConversations.get(userId) || [];
console.log(`Delete ${userConversationIds.length} dialogues for user ${userId}`);
let deletedCount = 0;
for (const conversationId of userConversationIds) {
try {
await ai.bot.deleteConversation({
botId: this.botId,
conversationId: conversationId,
});
deletedCount++;
console.log(`Deleted conversation: ${conversationId}`);
} catch (error) {
console.error(`Delete conversation fail: ${conversationId}`, error);
}
}
// Remove user dialogue records from memory
this.userConversations.delete(userId);
console.log(`Data clearing for user ${userId} completed, ${deletedCount} dialogues deleted`);
return deletedCount;
}
async deleteAllUserData(): Promise<number> {
const allUserIds = Array.from(this.userConversations.keys());
let totalDeleted = 0;
console.log(`Start cleaning ${allUserIds.length} user data`);
for (const userId of allUserIds) {
const deletedCount = await this.deleteUserConversations(userId);
totalDeleted += deletedCount;
}
console.log(`${totalDeleted} dialogues cleaned up in total`);
return totalDeleted;
}
async deleteUserDataByCondition(
condition: (userId: string, conversationIds: string[]) => boolean
): Promise<number> {
const usersToDelete: string[] = [];
for (const [userId, conversationIds] of this.userConversations.entries()) {
if (condition(userId, conversationIds)) {
usersToDelete.push(userId);
}
}
console.log(`Find ${usersToDelete.length} eligible users`);
let totalDeleted = 0;
for (const userId of usersToDelete) {
const deletedCount = await this.deleteUserConversations(userId);
totalDeleted += deletedCount;
}
return totalDeleted;
}
Add user dialogue history
addUserConversation(userId: string, conversationId: string) {
if (!this.userConversations.has(userId)) {
this.userConversations.set(userId, []);
}
this.userConversations.get(userId)!.push(conversationId);
}
// Get user dialogue statistics
getUserStats(): { totalUsers: number; totalConversations: number } {
let totalConversations = 0;
for (const conversationIds of this.userConversations.values()) {
totalConversations += conversationIds.length;
}
return {
totalUsers: this.userConversations.size,
totalConversations: totalConversations,
};
}
}
Usage Example
const dataManager = new UserDataManager("data-management-bot-id");
Add user dialogue history
dataManager.addUserConversation("user1", "conv-123");
dataManager.addUserConversation("user1", "conv-456");
dataManager.addUserConversation("user2", "conv-789");
// View statistics
const stats = dataManager.getUserStats();
console.log(`Number of users: ${stats.totalUsers}, Dialogues: ${stats.totalConversations}`);
// Delete data for a specific user
const deletedCount = await dataManager.deleteUserConversations("user1");
console.log(`Deleted ${deletedCount} dialogues for user1`);
// Conditional deletion: delete the user whose number of conversations exceeds threshold
const conditionDeleted = await dataManager.deleteUserDataByCondition(
(userId, conversationIds) => conversationIds.length > 5
);
console.log(`Deleted user data with ${conditionDeleted} dialogues exceeding 5`);
speechToText
function speechToText(props: {
botId: string;
engSerViceType: string;
voiceFormat: string;
url: string;
isPreview?: boolean;
}): Promise<SpeechToTextResult>;
Convert voice files into text, support various audio formats and language recognition.
- Support various audio formats such as MP3, WAV, and AAC -Support multiple language recognition engines -Process local or remote audio files -Suitable for voice assistant, meeting minutes, voice note and other scenarios
参数
props
object
Parameters for speech to text
返回
Promise
SpeechToTextResult
ASR result
示例
Convert voice file to text
const result = await ai.bot.speechToText({
botId: "speech-bot-id",
engSerViceType: "16k_zh",
voiceFormat: "mp3",
url: "https://example.com/audio.mp3",
});
console.log("Recognition result:", result.text);
console.log("Confidence:", result.confidence);
console.log("audio duration:", result.duration, "s");
console.log("Recognition language:", result.language);
// Voice assistant application
class VoiceAssistant {
private botId: string;
constructor(botId: string) {
this.botId = botId;
}
async processVoiceCommand(audioUrl: string): Promise<{
text: string;
response: string;
action?: string;
}> {
Convert speech to text
const speechResult = await ai.bot.speechToText({
botId: this.botId,
engSerViceType: "16k_zh",
voiceFormat: "mp3",
url: audioUrl,
});
console.log("ASR result:", speechResult.text);
// Generate reply based on recognition result
const response = await ai.bot.sendMessage({
botId: this.botId,
msg: speechResult.text,
});
let assistantReply = "";
for await (let text of response.textStream) {
assistantReply += text;
}
// Analyze whether to execute a specific operation
const action = this.analyzeCommand(speechResult.text);
return {
text: speechResult.text,
response: assistantReply,
action: action,
};
}
async createVoiceNote(audioUrl: string, title?: string): Promise<string> {
const result = await ai.bot.speechToText({
botId: this.botId,
engSerViceType: "16k_zh",
voiceFormat: "mp3",
url: audioUrl,
});
const noteContent = `
Voice note - ${title || new Date().toLocaleString()}
audio duration: ${result.duration}s
Recognition confidence: ${Math.round(result.confidence * 100)}%
Content:
${result.text}
`;
console.log("Voice note created successfully:");
console.log(noteContent);
return noteContent;
}
async batchTranscribe(
audioFiles: Array<{ url: string; name: string }>
): Promise<Map<string, string>> {
const results = new Map<string, string>();
console.log(`start batch conversion of ${audioFiles.length} audio files`);
for (const file of audioFiles) {
try {
const result = await ai.bot.speechToText({
botId: this.botId,
engSerViceType: "16k_zh",
voiceFormat: this.getFileFormat(file.url),
url: file.url,
});
results.set(file.name, result.text);
console.log(`✓ ${file.name}: conversion successful`);
} catch (error) {
console.error(`✗ ${file.name}: conversion failed`, error);
results.set(file.name, "conversion failed");
}
}
console.log("batch transcoding finished");
return results;
}
private analyzeCommand(text: string): string | undefined {
const commands = {
weather: "weather",
Time: "time",
play: "play",
Stop: "stop",
search: "search",
};
for (const [keyword, action] of Object.entries(commands)) {
if (text.includes(keyword)) {
return action;
}
}
return undefined;
}
private getFileFormat(url: string): string {
const extension = url.split(".").pop()?.toLowerCase();
return extension === "wav" ? "wav" : "mp3";
}
}
Usage Example
const voiceAssistant = new VoiceAssistant("voice-bot-id");
Process voice commands
const commandResult = await voiceAssistant.processVoiceCommand(
"voice-command.mp3"
);
console.log("Voice command:", commandResult.text);
console.log("Assistant reply:", commandResult.response);
if (commandResult.action) {
console.log("Operation execution:", commandResult.action);
}
Create voice note
const note = await voiceAssistant.createVoiceNote(
"meeting-recording.mp3",
meeting minutes
);
// Batch conversion of audio files
const audioFiles = [
{ url: "audio1.mp3", name: "Interview recording1" }
{ url: "audio2.wav", name: "Meeting recording2" }
{ url: "audio3.mp3", name: "Lecture recording3" }
];
const transcriptions = await voiceAssistant.batchTranscribe(audioFiles);
// Intelligent meeting minutes system
class MeetingTranscriptionSystem {
private botId: string;
constructor(botId: string) {
this.botId = botId;
}
async transcribeMeeting(
audioUrl: string,
participants: string[] = []
): Promise<{
transcript: string;
summary: string;
actionItems: string[];
speakerAnalysis: Map<string, number>;
}> {
Convert speech to text
const speechResult = await ai.bot.speechToText({
botId: this.botId,
engSerViceType: "16k_zh",
voiceFormat: "mp3",
url: audioUrl,
});
console.log("meeting recording transcoding finished, duration:", speechResult.duration, "s");
// Generate meeting summary
const summaryPrompt = `Generate a summary for the following meeting content, extract key decisions and action items:\n\n${speechResult.text}`;
const summaryResponse = await ai.bot.sendMessage({
botId: this.botId,
msg: summaryPrompt,
});
let summary = "";
for await (let text of summaryResponse.textStream) {
summary += text;
}
// Extract action items
const actionPrompt = `Extract specific action items and owners from the following meeting content:\n\n${speechResult.text}`;
const actionResponse = await ai.bot.sendMessage({
botId: this.botId,
msg: actionPrompt,
});
let actionText = "";
for await (let text of actionResponse.textStream) {
actionText += text;
}
const actionItems = actionText
.split("\n")
.filter((item) => item.trim().length > 0);
Analyze speech distribution (simple version)
const speakerAnalysis = this.analyzeSpeakerDistribution(
speechResult.text,
participants
);
return {
transcript: speechResult.text,
summary: summary,
actionItems: actionItems,
speakerAnalysis: speakerAnalysis,
};
}
async generateMeetingMinutes(
audioUrl: string,
meetingTitle: string,
participants: string[]
): Promise<string> {
const meetingData = await this.transcribeMeeting(audioUrl, participants);
const minutes = `
meeting minutes
========
meeting heading: ${meetingTitle}
meeting duration: ${
meetingData.transcript.length > 0
"about " + Math.ceil(meetingData.transcript.length / 200) + " minutes"
Unknown
}
Participants: ${participants.join(", ")}
Meeting Summary
--------
${meetingData.summary}
meeting minutes
--------
${meetingData.transcript}
Action Item
------
${meetingData.actionItems
.map((item, index) => `${index + 1}. ${item}`)
.join("\n")}
Speaking statistics
--------
${Array.from(meetingData.speakerAnalysis.entries())
.map(([speaker, count]) => `${speaker}: ${count} times speaking`)
.join("\n")}
`;
console.log("Meeting minutes generation completed");
return minutes;
}
private analyzeSpeakerDistribution(
transcript: string,
participants: string[]
): Map<string, number> {
const distribution = new Map<string, number>();
Initialize the count for each participant
participants.forEach((participant) => {
distribution.set(participant, 0);
});
// Simple analysis: count the number of occurrences of participant names
participants.forEach((participant) => {
const regex = new RegExp(participant, "gi");
const count = (transcript.match(regex) || []).length;
distribution.set(participant, count);
});
return distribution;
}
}
Usage Example
const meetingSystem = new MeetingTranscriptionSystem("meeting-bot-id");
// Generate meeting minutes
const minutes = await meetingSystem.generateMeetingMinutes(
"meeting-recording.mp3",
Quarter plan meeting
["Tom", "Jack", "Harry"]
);
console.log(minutes);
// Directly transcribe the meeting
const meetingData = await meetingSystem.transcribeMeeting("team-meeting.mp3");
console.log("Meeting Summary:", meetingData.summary);
console.log("Action Items:", meetingData.actionItems);
textToSpeech
function textToSpeech(props: {
botId: string;
voiceType: number;
text: string;
isPreview?: boolean;
}): Promise<TextToSpeechResult>;
Convert text to speech, support various speech types and voice types.
-Support various speech types and voice types -Adjustable parameters such as speaking rate and pitch -Support long text segment switch -Suitable for voice broadcast, audiobook, voice assistant and other scenarios
参数
props
object
Parameters for text to speech
返回
Promise
TextToSpeechResult
Result of text to speech
示例
Convert text to speech
const result = await ai.bot.textToSpeech({
botId: "tts-bot-id",
voiceType: 1, // Standard female voice
Hello, I am an AI voice assistant. Glad to serve you.
});
console.log("TTS completed:");
console.log("audio address:", result.audioUrl);
console.log("audio duration:", result.duration, "s");
console.log("file format:", result.format);
console.log("file size:", result.size, "byte");
// Intelligent voice assistant
class VoiceAssistant {
private botId: string;
private voiceType: number;
constructor(botId: string, voiceType: number = 1) {
this.botId = botId;
this.voiceType = voiceType;
}
async speakText(text: string): Promise<string> {
const result = await ai.bot.textToSpeech({
botId: this.botId,
voiceType: this.voiceType,
text: text,
});
console.log(`TTS completed: ${result.duration} seconds`);
// In practical applications, play audio here
this.playAudio(result.audioUrl);
return result.audioUrl;
}
async createAudioBook(
chapters: Array<{ title: string; content: string }>
): Promise<Map<string, string>> {
const audioFiles = new Map<string, string>();
console.log(`Start audiobook production, total ${chapters.length} chapters`);
for (const [index, chapter] of chapters.entries()) {
console.log(`Synthesising chapter ${index + 1}: ${chapter.title}`);
try {
const result = await ai.bot.textToSpeech({
botId: this.botId,
voiceType: this.voiceType,
text: chapter.content,
});
audioFiles.set(chapter.title, result.audioUrl);
console.log(`✓ Chapter ${index + 1} synthesis completed, duration: ${result.duration}s`);
} catch (error) {
console.error(`✗ Chapter ${index + 1} composition failure`, error);
}
}
console.log("Audiobook production completed");
return audioFiles;
}
async generateInteractiveStory(
storyTitle: string,
storyContent: string[]
): Promise<{
audioFiles: string[];
totalDuration: number;
}> {
const audioFiles: string[] = [];
let totalDuration = 0;
console.log(`Start generation of interactive story: ${storyTitle}`);
for (const [index, paragraph] of storyContent.entries()) {
console.log(`Synthesising content segment ${index + 1}`);
const result = await ai.bot.textToSpeech({
botId: this.botId,
voiceType: this.voiceType,
text: paragraph,
});
audioFiles.push(result.audioUrl);
totalDuration += result.duration;
console.log(`✓ Segment ${index + 1} synthesis completed, duration: ${result.duration}s`);
}
console.log(`Story generation completed, total duration: ${totalDuration}s`);
return { audioFiles, totalDuration };
}
async createVoiceAnnouncement(
message: string,
repeat: number = 1
): Promise<string[]> {
const announcements: string[] = [];
console.log(`Generate voice broadcast, repeat ${repeat} times`);
for (let i = 0; i < repeat; i++) {
const result = await ai.bot.textToSpeech({
botId: this.botId,
voiceType: this.voiceType,
text: message,
});
announcements.push(result.audioUrl);
console.log(`✓ Broadcast generation ${i + 1} completed`);
}
return announcements;
}
private playAudio(audioUrl: string): void {
// In practical applications, implement audio playback logic here
console.log("play audio:", audioUrl);
// Example: Use the HTML5 Audio API for playback
// const audio = new Audio(audioUrl);
// audio.play();
}
// Set speech type
setVoiceType(voiceType: number): void {
this.voiceType = voiceType;
console.log(`Speech type set: ${voiceType}`);
}
// Get supported speech type
getSupportedVoices(): Array<{ id: number; name: string }> {
return [
{ id: 1, name: "Standard female voice" },
{ id: 2, name: "Standard male voice" },
{ id: 3, name: "Emotional female voice" },
{ id: 4, name: "Emotional male voice" },
{ id: 5, name: "Child sound" },
{ id: 6, name: "Elderly sound" },
];
}
}
Usage Example
const voiceAssistant = new VoiceAssistant("voice-bot-id", 1);
Simple voice broadcast
const audioUrl = await voiceAssistant.speakText("Welcome to use voice assistant system.");
Produce an audiobook
const chapters = [
{ title: "Chapter One", content: "This is the beginning of a story..." }
{ title: "Chapter II", content: "The story continues..." }
{ title: "Chapter 3", content: "The climax of the story..." }
];
const audioBook = await voiceAssistant.createAudioBook(chapters);
Generate an interactive story
const storyContent = [
"Once there was a small village..."
"The village was home to an intelligent elderly man..."
"The elderly man taught the villagers much knowledge..."
];
const story = await voiceAssistant.generateInteractiveStory(
"Smart elderly"
storyContent
);
Create voice broadcast
const announcements = await voiceAssistant.createVoiceAnnouncement(
Please note, the system will already be under maintenance.
3
);
// Multilingual text to speech system
class MultiLanguageVoiceSystem {
private botId: string;
private languageVoices: Map<string, number> = new Map();
constructor(botId: string) {
this.botId = botId;
this.initializeLanguageVoices();
}
private initializeLanguageVoices(): void {
this.languageVoices.set("zh-CN", 1); // Chinese-standard female voice
this.languageVoices.set("en-US", 2); // English-standard male voice
this.languageVoices.set("ja-JP", 3); // Japanese-emotional female voice
this.languageVoices.set("ko-KR", 4); // Korean-emotional male voice
this.languageVoices.set("fr-FR", 1); // French-standard female voice
this.languageVoices.set("de-DE", 2); // German-standard male voice
}
async synthesizeMultilingualText(
texts: Map<string, string>
): Promise<Map<string, string>> {
const results = new Map<string, string>();
console.log(`Start synthesising multilingual text, total ${texts.size} languages`);
for (const [language, text] of texts.entries()) {
const voiceType = this.languageVoices.get(language) || 1;
console.log(`Synthesise ${language} language text`);
try {
const result = await ai.bot.textToSpeech({
botId: this.botId,
voiceType: voiceType,
text: text,
});
results.set(language, result.audioUrl);
console.log(`✓ ${language} language synthesis completed, duration: ${result.duration} seconds`);
} catch (error) {
console.error(`✗ ${language} language composition failure`, error);
results.set(language, "composition failure");
}
}
return results;
}
async createInternationalAnnouncement(
message: string
): Promise<Map<string, string>> {
const translations = await this.translateMessage(message);
return this.synthesizeMultilingualText(translations);
}
async generateLanguageLearningAudio(
language: string,
phrases: string[]
): Promise<Array<{ phrase: string; audioUrl: string }>> {
const learningAudios: Array<{ phrase: string; audioUrl: string }> = [];
const voiceType = this.languageVoices.get(language) || 1;
console.log(`Generate ${language} language learning audio, ${phrases.length} phrases`);
for (const phrase of phrases) {
try {
const result = await ai.bot.textToSpeech({
botId: this.botId,
voiceType: voiceType,
text: phrase,
});
learningAudios.push({
phrase: phrase,
audioUrl: result.audioUrl,
});
console.log(`✓ Phrase "${phrase}" audio generation completed`);
} catch (error) {
console.error(`✗ phrase "${phrase}" audio generation fail`, error);
}
}
return learningAudios;
}
async createTourGuideAudio(
language: string,
attractions: Array<{ name: string; description: string }>
): Promise<Map<string, string>> {
const guideAudios = new Map<string, string>();
const voiceType = this.languageVoices.get(language) || 1;
console.log(
Generate ${language} tour guide audio for ${attractions.length} scenic spots
);
for (const attraction of attractions) {
const description = `${attraction.name}:${attraction.description}`;
try {
const result = await ai.bot.textToSpeech({
botId: this.botId,
voiceType: voiceType,
text: description,
});
guideAudios.set(attraction.name, result.audioUrl);
console.log(`✓ Scenic spot "${attraction.name}" tour guide audio generation completed`);
} catch (error) {
console.error(`✗ scenic spot "${attraction.name}" tour guide audio generation fail`, error);
}
}
return guideAudios;
}
private async translateMessage(
message: string
): Promise<Map<string, string>> {
// In practical applications, here you can call the API
const translations = new Map<string, string>();
translations.set("zh-CN", message); // Chinese
translations.set("en-US", "Hello, this is an announcement."); // English
translations.set("ja-JP", "こんにちは、これはアナウンスです。"); // Japanese
translations.set("ko-KR", "안녕하세요, 공지사항입니다."); // Korean
return translations;
}
// Add new language support
addLanguageSupport(languageCode: string, voiceType: number): void {
this.languageVoices.set(languageCode, voiceType);
console.log(`Add language support: ${languageCode} -> speech type ${voiceType}`);
}
// Get the list of supported languages
getSupportedLanguages(): string[] {
return Array.from(this.languageVoices.keys());
}
}
Usage Example
const multiLangSystem = new MultiLanguageVoiceSystem("multilang-bot-id");
// Multilingual text synthesis
const multilingualTexts = new Map([
["en-US", "Welcome to use the multilingual speech system"]
["en-US", "Welcome to the multilingual voice system"],
["ja-JP", "Welcome to the multilingual voice system"],
]);
const audioResults = await multiLangSystem.synthesizeMultilingualText(
multilingualTexts
);
International Announcement Broadcast
const announcements = await multiLangSystem.createInternationalAnnouncement(
System maintenance notification
);
Language learning audio
const englishPhrases = ["Hello", "How are you?", "Thank you", "Goodbye"];
const learningAudios = await multiLangSystem.generateLanguageLearningAudio(
"en-US",
englishPhrases
);
Tour guide audio
const attractions = [
{ name: "The Forbidden City", description: "Ancient Chinese palace complex, a world heritage site" }
{ name: "The Great Wall", description: "Ancient Chinese military defense project, a world wonder" },
];
const guideAudios = await multiLangSystem.createTourGuideAudio(
"zh-CN",
attractions
);
getTextToSpeechResult
function getTextToSpeechResult(props: {
botId: string;
taskId: string;
isPreview?: boolean;
}): Promise<TextToSpeechResult>;
Retrieve the result of the text to speech task, query the completion status of the TTS task and the generated audio file.
-Querying the status and result of the async TTS task -Retrieve the generated audio file info -Support preview mode and official mode -Suitable for batch TTS, long text processing and other async scenarios
参数
props
object
Parameters for obtaining TTS results
返回
Promise
TextToSpeechResult
TTS task result
示例
// Querying TTS task results
const result = await ai.bot.getTextToSpeechResult({
botId: "tts-bot-id",
taskId: "task-123456",
});
console.log("Task status:", result.status);
console.log("Task progress:", result.progress, "%");
if (result.status === "completed") {
console.log("audio address:", result.audioUrl);
console.log("audio duration:", result.duration, "s");
console.log("file format:", result.format);
console.log("file size:", result.size, "byte");
} else if (result.status === "processing") {
console.log("Task is still in processing, please retry later");
} else if (result.status === "failed") {
console.log("task processing failed");
}
// Batch TTS task monitoring system
class BatchTTSMonitor {
private botId: string;
private taskQueue: Map<string, { text: string; createTime: Date }> =
new Map();
constructor(botId: string) {
this.botId = botId;
}
Add task to queue
addTask(taskId: string, text: string): void {
this.taskQueue.set(taskId, {
text: text,
createTime: new Date(),
});
console.log(`Task ${taskId} added to queue`);
}
// Monitor task progress
async monitorTaskProgress(
taskId: string,
maxWaitTime: number = 300
): Promise<TextToSpeechResult> {
const startTime = Date.now();
const checkInterval = 5000; // Check every 5 seconds
console.log(`Start monitoring task ${taskId} progress`);
while (true) {
const result = await ai.bot.getTextToSpeechResult({
botId: this.botId,
taskId: taskId,
});
console.log(
`Task ${taskId} status: ${result.status}, progress: ${result.progress}%`
);
if (result.status === "completed") {
console.log(`Task ${taskId} completed, audio duration: ${result.duration}s`);
this.taskQueue.delete(taskId);
return result;
}
if (result.status === "failed") {
console.error(`Task ${taskId} processing failed`);
this.taskQueue.delete(taskId);
throw new Error(`TTS task failure: ${taskId}`);
}
//Check whether timeout
if (Date.now() - startTime > maxWaitTime * 1000) {
console.error(`Task ${taskId} monitoring timeout`);
throw new Error(`TTS task timeout: ${taskId}`);
}
// Retry after waiting for a period of time
await this.sleep(checkInterval);
}
}
// Monitor all tasks in batch
async monitorAllTasks(): Promise<Map<string, TextToSpeechResult>> {
const results = new Map<string, TextToSpeechResult>();
const taskIds = Array.from(this.taskQueue.keys());
console.log(`Start monitoring ${taskIds.length} tasks`);
for (const taskId of taskIds) {
try {
const result = await this.monitorTaskProgress(taskId);
results.set(taskId, result);
} catch (error) {
console.error(`Task ${taskId} monitoring failed:`, error);
}
}
console.log(`Task monitoring completed, successful: ${results.size}/${taskIds.length}`);
return results;
}
// Get task statistics information
getTaskStats(): {
total: number;
completed: number;
processing: number;
failed: number;
} {
const stats = {
total: this.taskQueue.size,
completed: 0,
processing: 0,
failed: 0,
};
// In practical applications, statistics can be collected based on task status here
return stats;
}
// Clean up completed tasks
cleanupCompletedTasks(): void {
const completedTaskIds: string[] = [];
// In practical applications, here you can clean up completed task records
console.log(`${completedTaskIds.length} completed tasks cleaned up`);
}
private sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
}
Usage Example
const monitor = new BatchTTSMonitor("batch-tts-bot-id");
Add task to monitor queue
monitor.addTask("task-001", "This is the first TTS task");
monitor.addTask("task-002", "This is the second TTS task");
monitor.addTask("task-003", "This is the third TTS task");
// Monitor a single task
const result = await monitor.monitorTaskProgress("task-001");
console.log("task result:", result.audioUrl);
// Monitor all tasks in batch
const allResults = await monitor.monitorAllTasks();
// View task statistics
const stats = monitor.getTaskStats();
console.log("Task statistics:", stats);
// Long text to speech system
class LongTextTTSProcessor {
private botId: string;
private voiceType: number;
constructor(botId: string, voiceType: number = 1) {
this.botId = botId;
this.voiceType = voiceType;
}
// Process long text segments
async processLongText(
longText: string,
maxSegmentLength: number = 500
): Promise<string[]> {
const segments = this.splitText(longText, maxSegmentLength);
const audioUrls: string[] = [];
console.log(`Start processing long text, total ${segments.length} segments`);
for (const [index, segment] of segments.entries()) {
console.log(`Processing text segment ${index + 1}/${segments.length}`);
try {
// Submit a TTS task
const result = await ai.bot.textToSpeech({
botId: this.botId,
voiceType: this.voiceType,
text: segment,
});
// Wait for the task to complete
const finalResult = await this.waitForTaskCompletion(result.taskId);
audioUrls.push(finalResult.audioUrl);
console.log(
`✓ Segment ${index + 1} processed, duration: ${finalResult.duration}s`
);
} catch (error) {
console.error(`✗ Segment ${index + 1} processing failure`, error);
}
}
console.log(`Long text processing completed, generate ${audioUrls.length} audio files`);
return audioUrls;
}
// Wait for the task to complete
private async waitForTaskCompletion(
taskId: string,
maxWaitTime: number = 600
): Promise<TextToSpeechResult> {
const startTime = Date.now();
const checkInterval = 3000; // Check every 3 seconds
while (true) {
const result = await ai.bot.getTextToSpeechResult({
botId: this.botId,
taskId: taskId,
});
if (result.status === "completed") {
return result;
}
if (result.status === "failed") {
throw new Error(`TTS task failure: ${taskId}`);
}
//Check timeout
if (Date.now() - startTime > maxWaitTime * 1000) {
throw new Error(`TTS task timeout: ${taskId}`);
}
console.log(`Task ${taskId} progress: ${result.progress}%`);
await this.sleep(checkInterval);
}
}
// Text segmentation
private splitText(text: string, maxLength: number): string[] {
const segments: string[] = [];
let currentSegment = "";
const sentences = text.split(/[..?.!?]/);
for (const sentence of sentences) {
const trimmedSentence = sentence.trim();
if (!trimmedSentence) continue;
if (currentSegment.length + trimmedSentence.length + 1 <= maxLength) {
currentSegment += (currentSegment ? "." : "") + trimmedSentence;
} else {
if (currentSegment) {
segments.push(currentSegment + ".");
}
currentSegment = trimmedSentence;
}
}
if (currentSegment) {
segments.push(currentSegment + ".");
}
return segments;
}
// Merge audio files (in practical applications a specialized audio processing tool is required)
async mergeAudioFiles(audioUrls: string[]): Promise<string> {
console.log(`start merging ${audioUrls.length} audio files`);
// In practical applications, call the audio merge API here
// Return the first audio URL here as an example
return audioUrls[0];
}
Generate an audiobook
async createAudioBook(
bookTitle: string,
chapters: string[]
): Promise<Map<string, string[]>> {
const bookAudios = new Map<string, string[]>();
console.log(`Start audiobook production: ${bookTitle}, total ${chapters.length} chapters`);
for (const [index, chapter] of chapters.entries()) {
console.log(`Processing chapter ${index + 1}`);
const chapterAudios = await this.processLongText(chapter);
bookAudios.set(`Chapter ${index + 1}`, chapterAudios);
console.log(
`✓ Chapter ${index + 1} processed, ${chapterAudios.length} audio clips generated`
);
}
console.log(`Audiobook production completed: ${bookTitle}`);
return bookAudios;
}
private sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
}
Usage Example
const longTextProcessor = new LongTextTTSProcessor("longtext-bot-id", 1);
// Process long text
const longText = "This is a long text content that needs to be split into multiple paragraphs for text to speech...";
const audioSegments = await longTextProcessor.processLongText(longText);
Produce an audiobook
const bookChapters = [
"Chapter One: The beginning of the story..."
"Chapter II: The plot develops..."
"Chapter Three: The climax..."
"Chapter Four: The ending..."
];
const audioBook = await longTextProcessor.createAudioBook(
"My story"
bookChapters
);
// Merge audio files
const mergedAudio = await longTextProcessor.mergeAudioFiles(audioSegments);
console.log("Audio after merge:", mergedAudio);
Complete type definition
IBotCreateConversation
interface IBotCreateConversation {
botId: string;
title?: string;
}
IBotGetConversation
interface IBotGetConversation {
botId: string;
pageSize?: number;
pageNumber?: number;
isDefault?: boolean;
}
IBotDeleteConversation
interface IBotDeleteConversation {
botId: string;
conversationId: string;
}
IBotSpeechToText
interface IBotSpeechToText {
botId: string;
engSerViceType: string;
voiceFormat: string;
url: string;
isPreview?: boolean;
}
IBotTextToSpeech
interface IBotTextToSpeech {
botId: string;
voiceType: number;
text: string;
isPreview?: boolean;
}
IBotGetTextToSpeechResult
interface IBotGetTextToSpeechResult {
botId: string;
taskId: string;
isPreview?: boolean;
}
BaseChatModelInput
interface BaseChatModelInput {
model: string;
messages: Array<ChatModelMessage>;
temperature?: number;
topP?: number;
tools?: Array<FunctionTool>;
toolChoice?: "none" | "auto" | "custom";
maxSteps?: number;
onStepFinish?: (prop: IOnStepFinish) => unknown;
}
| BaseChatModelInput attribute name | data type | description |
|---|---|---|
| model | string | model name |
| messages | Array<ChatModelMessage> | message list |
| temperature | number | Sampling temperature, controls output randomness. |
| topP | number | Temperature sampling, consider results with probability mass top_p. |
| tools | Array<FunctionTool> | Available tool list for large model |
| toolChoice | string | Specify the way for the large model to select tools. |
| maxSteps | number | Maximum number of times to request the large model. |
| onStepFinish | (prop: IOnStepFinish) => unknown | The callback function that departs upon completion of a single request to the large model. |
BotInfo
interface BotInfo {
botId: string;
name: string;
introduction: string;
agentSetting: string;
welcomeMessage: string;
avatar: string;
background: string;
tags: Array<string>;
isNeedRecommend: boolean;
knowledgeBase: Array<string>;
type: string;
initQuestions: Array<string>;
enable: true;
}
IUserFeedback
interface IUserFeedback {
recordId: string;
type: string;
botId: string;
comment: string;
rating: number;
tags: Array<string>;
input: string;
aiAnswer: string;
}
ChatModelMessage
type ChatModelMessage =
| UserMessage
| SystemMessage
| AssistantMessage
| ToolMessage;
UserMessage
type UserMessage = {
role: "user";
content: string;
};
SystemMessage
type SystemMessage = {
role: "system";
content: string;
};
AssistantMessage
type AssistantMessage = {
role: "assistant";
content?: string;
tool_calls?: Array<ToolCall>;
};
ToolMessage
type ToolMessage = {
role: "tool";
tool_call_id: string;
content: string;
};
ToolCall
export type ToolCall = {
id: string;
type: string;
function: { name: string; arguments: string };
};
FunctionTool
Tool definition type.
type FunctionTool = {
name: string;
description: string;
fn: CallableFunction;
parameters: object;
};
| FunctionTool attribute name | data type | description |
|---|---|---|
| name | string | tool name |
| description | string | tool description. A clear tool description helps the large model meet the tool purpose. |
| fn | CallableFunction | The execution function of the tool. When the AI SDK parses out the large model response requires this tool to invoke, it will invoke this function and return the result to the large model. |
| parameters | object | The input parameters of the tool execution function. Require the use of JSON Schema format definition. |
IOnStepFinish
Input parameter type of the callback function triggered after the large model responds.
interface IOnStepFinish {
messages: Array<ChatModelMessage>;
text?: string;
toolCall?: ToolCall;
toolResult?: unknown;
finishReason?: string;
stepUsage?: Usage;
totalUsage?: Usage;
}
| IOnStepFinish attribute name | data type | description |
|---|---|---|
| messages | Array<ChatModelMessage> | List of all messages up to the current step. |
| text | string | Current response text. |
| toolCall | ToolCall | Tool called by the current response. |
| toolResult | unknown | Tool call result. |
| finishReason | string | The causes for large model inference ended. |
| stepUsage | Usage | Tokens spent in the current step. |
| totalUsage | Usage | Total tokens spent up to the current step. |
Usage
type Usage = {
completion_tokens: number;
prompt_tokens: number;
total_tokens: number;
};
IConversation
Agent session.
interface IConversation {
id: string;
envId: string;
ownerUin: string;
userId: string;
conversationId: string;
title: string;
startTime: string; // date-time format
createTime: string;
updateTime: string;
}