ai-ciopaas

AI智能语音客服交付对接 SDK。当前封装了文档中的登录、子账号、话术模板、JSON 外呼任务接口，并提供挂机流水回调的 TypeScript 类型。

安装

pnpm add ai-ciopaas

在当前 monorepo 内使用：

pnpm --filter ai-ciopaas build

初始化

baseUrl、apiAccessId、apiAccessSecret 都需要由接入项目在运行时传入。SDK 会自动调用 /api/login 获取并缓存 api_key 和 user_sn，过期前会自动刷新。

import { createAiCioPaasClient } from 'ai-ciopaas';

const client = createAiCioPaasClient({
	baseUrl: 'https://xxx.xxx.com',
	apiAccessId: process.env.CIOPAAS_API_ACCESS_ID!,
	apiAccessSecret: process.env.CIOPAAS_API_ACCESS_SECRET!,
});

const session = await client.login();
console.log(session.userSn, session.apiKey);

运行中切换配置：

client.updateCredentials({
	baseUrl: 'https://new-ciopaas.example.com',
	apiAccessId: 'new-access-id',
	apiAccessSecret: 'new-access-secret',
});

子账号

const subAccounts = await client.subAccounts.list({
	pageIndex: 0,
	pageSize: 20,
	user_name: '',
});

await client.subAccounts.create({
	user_name: 'demo001',
	contact: 'demo001',
	password: 'Demo001A123',
	re_password: 'Demo001A123',
	organization_id: 173,
	role_id: 366,
	max_call_count: 1,
	project_sn: 'projects|xxx',
	sdzj_phone: 'vos:900002',
	display_phone: '',
	callin_project_sn: 'projects|xxx',
	ext: '1',
	linkext: '2',
	sippwd: 'Demo001A123',
	project_name: '测试话术',
	auto_create: 1,
});

await client.subAccounts.update({
	user_name: 'demo001',
	contact: 'demo001',
	password: '',
	re_password: '',
	organization_id: 173,
	role_id: 366,
	max_call_count: 1,
	project_sn: 'projects|xxx',
});

await client.subAccounts.remove(['demo001']);

话术模板

const projects = await client.rhetoric.listProjects();
// client.projects 是 client.rhetoric 的别名

新建或追加外呼任务

const task = await client.outboundTasks.createJsonTask({
	source: '新建任务1',
	project_sn: 'projects|xxx',
	ai_user_sn: 'SYSUSER|子账号sn',
	is_zidong: 'on',
	client_info_json: {
		data: [
			{
				姓名: '张三',
				电话: '13800000000',
				地址: '深圳',
			},
		],
	},
	yd_display_phone: 'SYSUSER|子账号sn@vos:900002',
});

await client.outboundTasks.appendJsonTask({
	dial_task_main_sn: task.dial_task_main_sn,
	source: '追加任务1',
	project_sn: 'projects|xxx',
	ai_user_sn: 'SYSUSER|子账号sn',
	client_info_json: {
		data: [{ 姓名: '李四', 电话: '13900000000' }],
	},
});

密文传输 client_info_json：

await client.outboundTasks.createEncryptedJsonTask({
	source: '密文任务',
	project_sn: 'projects|xxx',
	ai_user_sn: 'SYSUSER|子账号sn',
	client_info_json: {
		data: [{ 姓名: '王五', 电话: '13700000000' }],
	},
});

任务导入模板

client_info_json 对应的模板可以直接从 /api/exportModel 获取。

获取 JSON 模板

const template = await client.outboundTasks.getImportTemplateJson({
	project_sn: 'projects|4a92f90b5339646b36e9805600820deb',
});

console.log(template);

直接下载 Excel 模板

const buffer = await client.outboundTasks.downloadImportTemplate({
	project_sn: 'projects|4a92f90b5339646b36e9805600820deb',
});
import { writeFile } from 'node:fs/promises';

await writeFile('import-template.xlsx', Buffer.from(buffer));

生成浏览器下载链接

const url = await client.outboundTasks.getImportTemplateDownloadUrl({
	project_sn: 'projects|4a92f90b5339646b36e9805600820deb',
});

console.log(url);

通用请求

如果后续文档新增接口，可以先用通用 post 方法接入。设置 auth: true 后会自动注入 api_key 和 user_sn。

const result = await client.post(
	'/api/someNewApi',
	{
		foo: 'bar',
	},
	{
		auth: true,
	},
);

错误处理

接口返回 code !== 0 或 rst !== 200 时会抛出 AiCioPaasError。api_key 过期时默认会重新登录并重试一次。

import { AiCioPaasError } from 'ai-ciopaas';

try {
	await client.rhetoric.listProjects();
} catch (error) {
	if (error instanceof AiCioPaasError) {
		console.error(error.code, error.message, error.endpoint);
	}
}

回调响应

挂机流水回调处理成功后，需要返回字符串 SUCCESS。

import {
	CIOPAAS_CALLBACK_SUCCESS,
	type OutboundTaskCallbackPayload,
} from 'ai-ciopaas';

export async function handleCallback(payload: OutboundTaskCallbackPayload) {
	// 建议按 payload.sn 或 payload.dial_task_main_sn 做幂等处理
	return CIOPAAS_CALLBACK_SUCCESS;
}