Back to Details

presence

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Presence - Complete API Reference

Presence - 完整API参考

Manage online status, track activity across devices, and sync presence information.
管理在线状态，跨设备追踪活动，并同步在线状态信息。

Chat Commands

聊天命令

View Status

查看状态

/presence                                   Show your status
/presence who                               Who's online
/presence activity                          Recent activity
/presence                                   Show your status
/presence who                               Who's online
/presence activity                          Recent activity

Set Status

设置状态

/presence online                            Set online
/presence away                              Set away
/presence dnd                               Do not disturb
/presence offline                           Appear offline
/presence status "In a meeting"             Custom status
/presence online                            Set online
/presence away                              Set away
/presence dnd                               Do not disturb
/presence offline                           Appear offline
/presence status "In a meeting"             Custom status

Devices

设备

/presence devices                           Your connected devices
/presence sync                              Force sync all devices
/presence devices                           Your connected devices
/presence sync                              Force sync all devices

TypeScript API Reference

TypeScript API 参考

Create Presence Service

创建Presence服务

typescript
import { createPresenceService } from 'clodds/presence';

const presence = createPresenceService({
  // Update interval
  heartbeatIntervalMs: 30000,

  // Auto-away after idle
  awayAfterMs: 300000,  // 5 minutes

  // Storage
  storage: 'redis',  // 'redis' | 'memory'
  redisUrl: process.env.REDIS_URL,
});
typescript
import { createPresenceService } from 'clodds/presence';

const presence = createPresenceService({
  // Update interval
  heartbeatIntervalMs: 30000,

  // Auto-away after idle
  awayAfterMs: 300000,  // 5 minutes

  // Storage
  storage: 'redis',  // 'redis' | 'memory'
  redisUrl: process.env.REDIS_URL,
});

Get Status

获取状态

typescript
// Get own status
const status = await presence.getStatus(userId);

console.log(`Status: ${status.status}`);  // 'online' | 'away' | 'dnd' | 'offline'
console.log(`Custom: ${status.customStatus}`);
console.log(`Last seen: ${status.lastSeen}`);
console.log(`Device: ${status.activeDevice}`);

// Get multiple users
const statuses = await presence.getStatuses(['user-1', 'user-2', 'user-3']);
typescript
// Get own status
const status = await presence.getStatus(userId);

console.log(`Status: ${status.status}`);  // 'online' | 'away' | 'dnd' | 'offline'
console.log(`Custom: ${status.customStatus}`);
console.log(`Last seen: ${status.lastSeen}`);
console.log(`Device: ${status.activeDevice}`);

// Get multiple users
const statuses = await presence.getStatuses(['user-1', 'user-2', 'user-3']);

Set Status

设置状态

typescript
// Set status
await presence.setStatus(userId, 'online');
await presence.setStatus(userId, 'away');
await presence.setStatus(userId, 'dnd');
await presence.setStatus(userId, 'offline');

// Set custom status message
await presence.setCustomStatus(userId, 'Trading BTC');

// Clear custom status
await presence.clearCustomStatus(userId);
typescript
// Set status
await presence.setStatus(userId, 'online');
await presence.setStatus(userId, 'away');
await presence.setStatus(userId, 'dnd');
await presence.setStatus(userId, 'offline');

// Set custom status message
await presence.setCustomStatus(userId, 'Trading BTC');

// Clear custom status
await presence.clearCustomStatus(userId);

Activity Tracking

活动追踪

typescript
// Record activity
await presence.recordActivity(userId, {
  type: 'message',
  channelId: 'telegram-123',
  timestamp: Date.now(),
});

// Get recent activity
const activity = await presence.getActivity(userId, {
  limit: 10,
  since: Date.now() - 3600000,  // Last hour
});

for (const event of activity) {
  console.log(`${event.type} at ${event.timestamp}`);
  console.log(`  Channel: ${event.channelId}`);
}
typescript
// Record activity
await presence.recordActivity(userId, {
  type: 'message',
  channelId: 'telegram-123',
  timestamp: Date.now(),
});

// Get recent activity
const activity = await presence.getActivity(userId, {
  limit: 10,
  since: Date.now() - 3600000,  // Last hour
});

for (const event of activity) {
  console.log(`${event.type} at ${event.timestamp}`);
  console.log(`  Channel: ${event.channelId}`);
}

Device Presence

设备在线状态

typescript
// Get user's devices
const devices = await presence.getDevices(userId);

for (const device of devices) {
  console.log(`${device.id}: ${device.name}`);
  console.log(`  Status: ${device.status}`);
  console.log(`  Last seen: ${device.lastSeen}`);
  console.log(`  Active: ${device.isActive}`);
}

// Set device status
await presence.setDeviceStatus(userId, deviceId, 'online');
typescript
// Get user's devices
const devices = await presence.getDevices(userId);

for (const device of devices) {
  console.log(`${device.id}: ${device.name}`);
  console.log(`  Status: ${device.status}`);
  console.log(`  Last seen: ${device.lastSeen}`);
  console.log(`  Active: ${device.isActive}`);
}

// Set device status
await presence.setDeviceStatus(userId, deviceId, 'online');

Who's Online

在线用户列表

typescript
// Get online users
const online = await presence.getOnlineUsers({
  channelId: 'telegram-123',  // Optional: filter by channel
});

for (const user of online) {
  console.log(`${user.name}: ${user.status}`);
}
typescript
// Get online users
const online = await presence.getOnlineUsers({
  channelId: 'telegram-123',  // Optional: filter by channel
});

for (const user of online) {
  console.log(`${user.name}: ${user.status}`);
}

Event Handlers

事件处理器

typescript
// Status changes
presence.on('statusChange', (userId, oldStatus, newStatus) => {
  console.log(`${userId}: ${oldStatus} -> ${newStatus}`);
});

// User came online
presence.on('online', (userId) => {
  console.log(`${userId} is now online`);
});

// User went offline
presence.on('offline', (userId) => {
  console.log(`${userId} went offline`);
});
typescript
// Status changes
presence.on('statusChange', (userId, oldStatus, newStatus) => {
  console.log(`${userId}: ${oldStatus} -> ${newStatus}`);
});

// User came online
presence.on('online', (userId) => {
  console.log(`${userId} is now online`);
});

// User went offline
presence.on('offline', (userId) => {
  console.log(`${userId} went offline`);
});

Sync Across Devices

跨设备同步

typescript
// Force sync
await presence.sync(userId);

// Get sync status
const syncStatus = await presence.getSyncStatus(userId);
console.log(`Devices synced: ${syncStatus.synced}/${syncStatus.total}`);
console.log(`Last sync: ${syncStatus.lastSync}`);
typescript
// Force sync
await presence.sync(userId);

// Get sync status
const syncStatus = await presence.getSyncStatus(userId);
console.log(`Devices synced: ${syncStatus.synced}/${syncStatus.total}`);
console.log(`Last sync: ${syncStatus.lastSync}`);

Status Types

状态类型

StatusDescription
online
Active and available
away
Idle/inactive
dnd
Do not disturb
offline
Not available
Status描述
online
活跃且可用
away
空闲/未活跃
dnd
请勿打扰
offline
不可用

Auto-Away

自动离开

Presence automatically changes to 
away
after inactivity:
typescript
const presence = createPresenceService({
  awayAfterMs: 300000,    // 5 min idle -> away
  offlineAfterMs: 3600000, // 1 hour idle -> offline
});
Presence会在无操作后自动切换为
away
状态：
typescript
const presence = createPresenceService({
  awayAfterMs: 300000,    // 5 min idle -> away
  offlineAfterMs: 3600000, // 1 hour idle -> offline
});

Multi-Device Sync

多设备同步

When user is active on multiple devices:
  • Most recent activity determines primary device
  • Status syncs across all devices
  • Custom status shared everywhere
当用户在多个设备上活跃时：
  • 最新的活动记录决定主设备
  • 状态在所有设备间同步
  • 自定义状态在所有端共享

Best Practices

最佳实践

  1. Use heartbeats — Keep status accurate
  2. Set away appropriately — Don't spam status changes
  3. Custom status — Let others know what you're doing
  4. Review devices — Keep device list clean
  5. DND for focus — Mute notifications during trades
  1. 使用心跳机制 — 保持状态准确
  2. 合理设置离开状态 — 避免频繁发送状态变更请求
  3. 自定义状态 — 让其他人了解你当前的状态
  4. 定期检查设备列表 — 保持设备列表整洁
  5. 专注时开启DND — 交易期间静音通知