English | 简体中文
Official Node.js and Browser SDK for Coze(or 扣子) API platform.
npm install @coze/api
# or
pnpm install @coze/api
import { CozeAPI, COZE_COM_BASE_URL, ChatStatus, RoleType } from '@coze/api';
// Initialize client with your Personal Access Token
const client = new CozeAPI({
token: 'your_pat_token', // Get your PAT from https://www.coze.com/open/oauth/pats
// or
// token: async () => {
// // refresh token if expired
// return 'your_oauth_token';
// },
baseURL: COZE_COM_BASE_URL,
});
// Simple chat example
async function quickChat() {
const v = await client.chat.createAndPoll({
bot_id: 'your_bot_id',
additional_messages: [{
role: RoleType.User,
content: 'Hello!',
content_type: 'text',
}],
});
if (v.chat.status === ChatStatus.COMPLETED) {
for (const item of v.messages) {
console.log('[%s]:[%s]:%s', item.role, item.type, item.content);
}
console.log('usage', v.chat.usage);
}
}
- 🌐 Full API Support: Covers all Coze Open Platform APIs
- 🔐 Multiple Auth Methods: PAT, OAuth, JWT, OAuth PKCE
- 🔄 Streaming Support: Real-time responses for chat and workflow
- 🔄 Websocket Support: Real-time responses for chat, speech, and transcriptions
- 🌍 Cross-Platform: Works in Node.js (≥14) and modern browsers
- ⚙️ Configurable: Timeout, headers, signal, debug options
- Personal Access Token (Simplest)
const client = new CozeAPI({
token: 'your_pat_token',
baseURL: COZE_COM_BASE_URL, // Use COZE_CN_BASE_URL for China region
});
- Other Auth Methods
- OAuth Web Application
- OAuth PKCE
- JWT
- Device Code Flow
View authentication examples →
import { CozeAPI, ChatEventType, RoleType } from '@coze/api';
async function streamChat() {
const stream = await client.chat.stream({
bot_id: 'your_bot_id',
additional_messages: [{
role: RoleType.User,
content: 'Hello!',
content_type: 'text',
}],
});
for await (const part of stream) {
if (part.event === ChatEventType.CONVERSATION_MESSAGE_DELTA) {
process.stdout.write(part.data.content); // Real-time response
}
}
}
import { CozeAPI, RoleType, WebsocketsEventType } from '@coze/api';
async function wsChat() {
const ws = await client.websockets.chat.create('your_bot_id');
ws.onopen = () => {
ws.send({
id: 'event_id',
event_type: WebsocketsEventType.CHAT_UPDATE,
data: {
chat_config: {
auto_save_history: true,
user_id: 'uuid',
meta_data: {},
custom_variables: {},
extra_params: {},
},
},
});
ws.send({
id: 'event_id',
event_type: WebsocketsEventType.CONVERSATION_MESSAGE_CREATE,
data: {
role: RoleType.User,
content: 'tell me a joke',
content_type: 'text',
},
});
};
ws.onmessage = (data, event) => {
if (data.event_type === WebsocketsEventType.ERROR) {
if (data.data.code === 4100) {
console.error('Unauthorized Error', data);
} else if (data.data.code === 4101) {
console.error('Forbidden Error', data);
} else {
console.error('WebSocket error', data);
}
ws.close();
return;
}
if (data.event_type === WebsocketsEventType.CONVERSATION_MESSAGE_DELTA) {
console.log('on message delta', data.data);
} else if (
data.event_type === WebsocketsEventType.CONVERSATION_CHAT_COMPLETED
) {
console.log('on chat completed', data.data);
}
};
ws.onerror = error => {
console.error('WebSocket error', error);
ws.close();
};
}
const client = new CozeAPI({
token: '', // use proxy token in server
baseURL: 'http://localhost:8080/api',
});
import { WsSpeechClient, WebsocketsEventType } from '@coze/api/ws-tools';
// Initialize
const client = new WsSpeechClient({
token: 'your_pat_token',
baseWsURL: COZE_CN_BASE_WS_URL,
allowPersonalAccessTokenInBrowser: true, // optional
});
// Listen for all downstream events (including error)
client.on('data', data => {
console.log('[speech] ws data', data);
});
// Or, listen for a single event
client.on(WebsocketsEventType.ERROR, data => {
console.error('[speech] ws error', data);
});
// Listen for playback completed event
client.on('completed', () => {
console.log('[speech] playback completed');
});
// Connect
try {
await client.connect({voiceId: 'your_voice_id'});
console.log('[speech] ws connect success');
} catch (error) {
console.error('[speech] ws connect error', error);
return;
}
// Send message and play
client.appendAndComplete(message);
// Interrupt
client.interrupt();
// Disconnect, destroy instance
client.disconnect();
// Pause speech playback
client.pause();
// Resume speech playback
client.resume();
// Toggle speech playback
client.togglePlay();
// Check if speech is playing
client.isPlaying();
// Send text fragment
client.append(message);
// End sending text
client.complete();
Feature | Description | Example |
---|---|---|
Chat | Text conversations | chat.ts |
Bot Management | Create and manage bots | bot.ts |
Datasets | Document management | datasets.ts |
Workflow | Run workflow | workflow.ts |
Voice | Speech synthesis | voice.ts |
Templates | Template management | templates.ts |
Chat(websocket) | Text and voice chat | chat.ts |
Speech(websocket) | Text to speech | speech.ts |
Transcriptions(websocket) | Speech to text | transcriptions.ts |
View all examples → | ||
Websocket Events → |
# Install dependencies
rush update # If `rush` command is not installed, see ../../README.md
# Run tests
npm run test
cd examples/coze-js-node
npm run run-preinstall
npm install
npx tsx ./src/chat.ts
# For China region (api.coze.cn)
COZE_ENV=zh npx tsx ./src/chat.ts # macOS/Linux
set "COZE_ENV=zh" && npx tsx ./src/chat.ts # Windows CMD
$env:COZE_ENV="zh"; npx tsx ./src/chat.ts # Windows PowerShell
cd examples/coze-js-web
rush build
npm start
For detailed API documentation and guides, visit: