Webhook 与通知

通过 Webhook 接收实时事件通知，并轮询获取主动智能体消息。

Webhook 概述

注册 Webhook

通过提供 URL 和可选的身份验证头来订阅事件类型。

const webhook = await client.webhooks.register("agent.message", {
  webhookUrl: "https://your-server.com/webhooks/sonzai",
  authHeader: "Bearer your-webhook-secret",
});

console.log(webhook.secret); // use to verify webhook signatures

Webhook 事件

您可以订阅的事件类型：

agent.message智能体发送主动消息

agent.mood_change智能体情绪发生显著变化

agent.memory_added新记忆被提取

agent.breakthrough重要的人格里程碑

agent.wakeup计划唤醒已触发

agent.consolidation记忆整合完成

管理 Webhook

列出、删除、检查投递尝试以及轮换已注册 Webhook 的密钥。

// List all webhooks
const webhooks = await client.webhooks.list();

// Delete a webhook
await client.webhooks.delete("agent.message");

// View delivery attempts
const attempts = await client.webhooks.listDeliveryAttempts("agent.message");

// Rotate webhook secret
const rotated = await client.webhooks.rotateSecret("agent.message");

项目级 Webhook

在项目级别注册 Webhook，以接收项目内所有智能体的事件。

await client.webhooks.registerForProject("project-id", "agent.message", {
  webhookUrl: "https://your-server.com/webhooks/project",
});

const projectWebhooks = await client.webhooks.listForProject("project-id");

主动通知（轮询）

智能体可以生成由唤醒、情绪变化或其他内部事件触发的主动消息。当推送投递不可行时，轮询获取待处理的通知。

// List pending notifications
const notifications = await client.notifications.list("agent-id", {
  userId: "user-123",
  status: "pending",
});

for (const notif of notifications.items) {
  console.log(notif.type, notif.content);

  // Mark as consumed after processing
  await client.notifications.consume("agent-id", notif.id);
}

// View notification history
const history = await client.notifications.history("agent-id", {
  userId: "user-123",
  limit: 50,
});

安排唤醒

安排主动回访，让智能体在特定时间主动联系用户。

const wakeup = await client.agents.scheduleWakeup("agent-id", {
  userId: "user-123",
  scheduledAt: "2026-04-05T09:00:00Z",
  context: "Check in about the job interview preparation",
});

Webhook 与通知的区别

Webhook（推送） 通过 HTTP POST 实时将事件投递到您的服务器。当您有能够接收回调的服务器且需要即时事件通知时使用 Webhook。

通知（轮询） 将主动智能体消息排队，供您按需获取。当您的客户端无法接收入站 HTTP 请求时（如移动应用、浏览器客户端），或当您希望按自己的计划批量处理通知时使用轮询。

← 状态、工具与引导记忆感知聊天→