Webhookを介したリアルタイムのイベント通知の受信と、プロアクティブなエージェントメッセージのポーリング。

Webhookの概要

イベント発生時にHTTP POSTコールバックを受信するためにWebhook URLを登録します。プラットフォームは購読したイベントが発火するたびに署名付きJSONペイロードをエンドポイントに送信し、ポーリングなしでリアルタイム統合を実現します。

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); // Webhook署名の検証に使用

Webhookイベント

購読できるイベントタイプ：

agent.message: エージェントがプロアクティブメッセージを送信
agent.mood_change: エージェントのムードが大きく変化
agent.memory_added: 新しいメモリが抽出された
agent.breakthrough: 重要なパーソナリティマイルストーン
agent.wakeup: スケジュールされたウェイクアップがトリガー
agent.consolidation: メモリ統合が完了

Webhookの管理

登録済みWebhookの一覧表示・削除・配信試行の確認・シークレットのローテーション。

// すべてのWebhookを一覧表示
const webhooks = await client.webhooks.list();

// Webhookを削除
await client.webhooks.delete("agent.message");

// 配信試行を確認
const attempts = await client.webhooks.listDeliveryAttempts("agent.message");

// Webhookシークレットをローテーション
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");

プロアクティブ通知（ポーリング）

エージェントはウェイクアップ・ムードシフト・その他の内部イベントによってトリガーされたプロアクティブメッセージを生成できます。プッシュ配信が難しい場合は保留中の通知をポーリングします。

// 保留中の通知を一覧表示
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);

// 処理後に消費済みとしてマーク
await client.notifications.consume("agent-id", notif.id);
}

// 通知履歴を確認
const history = await client.notifications.history("agent-id", {
userId: "user-123",
limit: 50,
});

ウェイクアップのスケジュール

ウェイクアップは自動です

エージェントは関係コンテキスト・会話パターン・感情シグナルに基づいて自動的に独自のウェイクアップをスケジュールします——これはすべてコンテキストエンジンが処理します。1つがトリガーされると agent.wakeup Webhookが発火します。

以下の手動スケジューリングは補完的なものです——ビジネスイベントに関連した特定のアウトリーチをトリガーしたい場合に使用します（購入後のフォローアップ・誕生日チェックイン・定期的なワークフローリマインダーなど）。

エージェントが指定した時間にユーザーに連絡を取るプロアクティブチェックインをスケジュールします：

const wakeup = await client.agents.scheduleWakeup("agent-id", {
userId: "user-123",
checkType: "interest_check",
intent: "Check in about the job interview preparation",
delayHours: 24, // 今から24時間後にスケジュール
});

Webhookと通知の使い分け

Webhook（プッシュ） はHTTP POST経由でリアルタイムにサーバーにイベントを配信します。コールバックを受信できるサーバーがあり、イベントの即時通知が必要な場合にWebhookを使用します。

通知（ポーリング） はプロアクティブなエージェントメッセージをキューに入れてオンデマンドで取得できるようにします。クライアントがインバウンドHTTPリクエストを受信できない場合（モバイルアプリ・ブラウザクライアント）や、独自のスケジュールで通知をバッチ処理したい場合にポーリングを使用します。

実践ガイド

3つのオーディエンスはすべてWebhookと通知を使用しますが、理由は大きく異なります。

クライアントから通知をポーリング。 ほとんどのコンパニオンはモバイルアプリやブラウザで動作するため、インバウンドWebhookを受け付けられません。30〜60秒ごとか、アプリがフォアグラウンドになったときにポーリングします。

プロアクティブウェイクアップこそがコンパニオンを生き生きとさせるものです。 控えめに使用してください——アクティブユーザーには1日に1回、それ以外はより少なく。プラットフォームは関係コンテキストに基づいて自動スケジュールします。ストーリーの節目のために追加でトリガーすることもできます。

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

for (const n of pending.notifications) {
  renderCompanionBubble(n.content);
  await client.agents.notifications.consume("agent-id", n.notificationId);
}

スケジュールしすぎないでください。 頻繁な未促求メッセージはすぐにハラスメントになります。

Webhook＆通知