creating-ai-subscription

プロンプトサブスクリプションの作成

使用するタイミング

サブスクリプションは、PostHog のレポートを定期的なスケジュールでメール、Slack、または Microsoft Teams に配信します。サブスクリプションには、設定するフィールドによって区別される 3 種類があります。種類は読み取り専用の resource_type から判別され、返されます。

• insight — 既存のインサイト 1 件の定期スナップショット（resource_type: "insight"）
• dashboard — ダッシュボードのタイルの定期スナップショット（resource_type: "dashboard"）
• prompt — 自由記述のプロンプトから定期的にAI が生成するレポート：LLM がプロジェクトのデータに対する HogQL を計画・実行し、各実行時に新しいマークダウンレポートを作成します（resource_type: "ai_prompt"）

このスキルは、prompt の種類を使う場合に適用します。つまり、既存のインサイトやダッシュボードの定期スナップショット、または一度限りのレポートではなく、X の定期的な AI 要約（毎日、毎週、毎月、毎年など、任意の頻度）をユーザーが求めている場合です。価値の中心が、固定のグラフではなく、LLM がクエリ内容を判断してレポートにまとめるという 分析そのもの にある場合に、プロンプトサブスクリプションを選んでください。インサイトまたはダッシュボードのサブスクリプションでは、prompt の代わりに insight／dashboard を設定します。その場合、以下の AI に関する制約は適用されません。

まずはダッシュボードまたはインサイトのサブスクリプションを優先してください。 プロンプトサブスクリプションは最も負荷の高い選択肢であり、LLM が独自に HogQL を作成するため、保存済みのインサイトやダッシュボードに表示される数値と異なる場合があります。（a）ユーザーが自由記述のレポートや AI が作成するレポートを明確に求めている場合、または（b）既存のインサイトやダッシュボードでは要望を満たせず、価値の中心が本当に分析そのものにある場合に限って使用してください。既存のダッシュボードまたはインサイトの主要な数値を定期的に受け取りたい場合は、「毎日これを投稿するスカウト／ボットを設定して」のような表現であっても、通常は summary_enabled: true を指定したダッシュボード（またはインサイト）のサブスクリプションが適しています。ユーザーがプロンプトサブスクリプションを希望していることを明確にしている場合はその意向を尊重してください。ただし、判断が曖昧な場合は、こちらを提案して先に確認してください。最適な手順については managing-subscriptions を参照してください。

このスキルでは、サブスクリプションの作成を扱います。作成後は、同じ subscriptions-* ツールでライフサイクルを管理します（以下を参照）。サブスクリプションの一覧表示、編集／無効化／再有効化、テスト配信の送信、削除ができます。

ツール

ツール	目的
posthog:subscriptions-create	定期的なプロンプトサブスクリプションを作成します
posthog:subscriptions-list	作成を確認し、既存のサブスクリプションを調べます
posthog:subscriptions-partial-update	編集、無効化（enabled: false）、再有効化を行います
posthog:subscriptions-test-delivery-create	配信先にテスト配信をすぐに送信します
posthog:subscriptions-delete	論理削除します（今後の配信をすべて停止します）
posthog:integrations-list	Slack の integration_id を検索します（kind=slack で絞り込みます）
posthog:integrations-channels-retrieve	Slack インテグレーションのチャンネルを一覧表示します（id と name）

呼び出す前に必要な条件

このエンドポイントには作成時のゲートが3つあり、いずれかを満たさない場合は400が返されます。

1. PostHog Cloud、または DEBUG=true — セルフホストの本番環境は対象外です（LLM の呼び出しは PostHog 管理のキーを経由します）。
2. 組織レベルで「AI data processing approved」が有効 — Org settings → Data → AI data processing で有効にする必要があります。組織のユーザーが、まず AI 機能の利用にオプトインする必要があります。
3. 組織でプロンプトのサブスクリプションが有効 — PostHog が管理するロールアウトフラグです。無効の場合、その組織にはまだアクセスが許可されていません。有効化を PostHog に依頼するようユーザーに伝えてください（セルフサービスで切り替える方法はありません）。

3つの条件のいずれかを満たしていない場合は、そこで止め、どの条件を修正すべきかユーザーに伝えてください。ツールを再度呼び出しても解決しません。

アクセストークンには、subscription:write に加えて query:read スコープも必要です。プロンプトのサブスクリプションは、プロジェクトのデータに対して LLM が生成した HogQL を実行するため、バックエンドでは作成、編集／再有効化、テスト配信、削除のいずれにもクエリアクセスが必要です。subscription:write だけのトークンは403で拒否されます。

必須引数

prompt: "..."                         # ≤4000 chars; setting this (with no insight/dashboard) makes it a prompt sub → resource_type "ai_prompt"
target_type: "email" | "slack" | "teams"  # the only delivery channels the API accepts
target_value: "..."                   # comma-separated emails, "<channel_id>|<channel_name>", or a Microsoft Teams webhook URL
frequency: "daily" | "weekly" | "monthly" | "yearly"
interval: 1                            # 1 = every tick; 2 = every other tick; etc.
start_date: "2026-09-15T09:30:00Z"   # anchors the recurrence + time-of-day; hour and half-hour slots are supported; need not be in the future
title: "..."                          # display name in the subscriptions list
send_test_now: false                   # set true only after the user approves an immediate delivery

送信する resource_type 引数はありません。種別は設定したフィールド（prompt ⇒ AI レポート）から導出され、読み取り専用の resource_type として返されます。

任意の引数

byweekday: ['monday', 'wednesday'] # weekly only — days the rrule fires
bysetpos: 1 # most useful with monthly; requires byweekday — e.g. byweekday:['monday']+bysetpos:-1 = last Monday
count: 10 # limit scheduled recurrence occurrences; manual and immediate deliveries do not count
until_date: '2026-12-31T00:00:00Z' # stop on/before this date
integration_id: 42 # Slack only — required; from integrations-list (see "Slack target")

Slack の宛先

target_value は <channel_id>|<channel_name>（インテグレーションが返す形式）である必要があります。次の3つの手順で作成します。

1. posthog:integrations-list を kind=slack で絞り込み、Slack インテグレーションの id を選択します。
2. その id を指定して posthog:integrations-channels-retrieve を実行し、チャンネルを選択します。各チャンネルの id と name が返されるので、それらを <id>|<name> の形式に組み立てて target_value に設定します。
3. そのインテグレーションの id を integration_id として渡します。サブスクリプションは特定の Slack インテグレーションに紐付けられるため、別の場所で再接続しても配信先が誤って変更されません。

Teams の宛先

target_value には、レポートを投稿するチャンネルの完全な Webhook URL を指定する必要があります。ユーザーはそのチャンネルに Workflows アプリを追加し、Webhook 要求を受信したときにチャンネルへ投稿するテンプレートを選択してから、URL をあなたに貼り付けます。別のテンプレートの URL を指定してもエラーなく保存されますが、レポートはチャンネルに届きません。参照する Teams インテグレーションはないため、integration_id は省略してください。

URL は https である必要があります。subscriptions-create が target_value を拒否した場合、その URL は Teams Webhook ではありません。同じテンプレートを使って作成し直し、URL 全体を貼り付けるようユーザーに依頼してください。後で更新する際は、保存済み URL を維持するために target_value を省略してください。API は URL をホスト名のみで返し、マスクされた値は拒否されます。

作成前

作成する前に、一致するサブスクリプションを一覧表示してください。 プロンプト、タイトル、配信先、スケジュール、有効状態を比較します。 プロンプトのテキストとタイトルはどちらも search に一致します。

作成は冪等ではありません。 作成要求がタイムアウトしたり、結果が不確かな状態で返された場合は、再試行する前に一致するサブスクリプションを一覧表示してください。 重複を特定するために、マスクされた Teams Webhook のホスト名を使わないでください。

ユーザーに、すぐに配信してよいか確認してください。 ユーザーが承認しない限り、send_test_now: false を設定してください。

例

毎週月曜の朝にメールで送信する AI サマリー

prompt: 'Top events week over week, with the biggest drops and any new failure modes called out.'
target_type: email
target_value: [email protected]
frequency: weekly
interval: 1
byweekday: ['monday']
start_date: '2026-09-14T08:00:00Z'
title: 'Weekly product pulse'
send_test_now: false

毎日午前9時に Slack レポートを送信

prompt: "Yesterday's sign-ups, where they came from, and any errors they hit during onboarding."
target_type: slack
target_value: 'C0123456789|growth-updates' # <channel_id>|<channel_name>; only the channel id is used, the name is cosmetic
integration_id: 42
frequency: daily
interval: 1
start_date: '2026-09-15T09:00:00Z'
title: 'Daily onboarding watch'
send_test_now: false

注意点

• Teams の webhook URL は認証情報です。 これを知っている人は誰でもチャンネルに投稿できるため、API はそのホストのみを返します。target_value としてのみ渡してください。ユーザーに返したり、確認メッセージ、要約、エラーレポートに記載したりしないでください。
• 種類は変更できません。 設定されているリレーションから導出されるため、insight または dashboard のサブスクリプションを、後から prompt サブスクリプションに変更することはできません（その逆も同様です）。insight サブスクリプションに prompt を追加する PATCH は拒否されます。作成時に適切な種類を選択してください。
• 以前に自動無効化された prompt サブスクリプションを再度有効にするには、2 つの前提条件を満たす必要があり、どちらも PATCH で検証されます。（1）有効な prompt があること。これはすでに行に保存されているものでも、PATCH 本文で新たに指定するものでもかまいません（保存済みの prompt がまだ有効なら {"enabled": true} だけで機能しますが、無効化の原因が無効な prompt だった場合は、適切な prompt を指定するまで拒否されます）。（2）元の作成者が引き続きアクティブなユーザーであること。そのアカウントが無効化されている場合、サブスクリプションは再度有効にできません（prompt を指定しても解決しないため、代わりに作成し直してください）。
• next_delivery_date は rrule からサーバー側で計算されます。 手動で設定しようとしないでください。読み取り専用です。最初の配信は、現在時刻から短い猶予（現在は約 15 分）を確保できる start_date の最初の発生時に実行されるため、数秒後の start_date を指定すると次の発生時まで繰り越されます。
• 一時的な送信失敗は再試行され、恒久的な失敗のみ自動無効化されます。 一時的な失敗（Slack のレート制限、SMTP の一時的な障害、ネットワーク障害）はその配信を失敗させ、実行中に Temporal によって再試行された後、次のスケジュール時刻に再度実行されます。サブスクリプションは自動無効化されないため、問題を修正するまで、継続的に失敗するチャンネルへの配信は毎回再試行されます。自動無効化されるのは、Slack 連携の切断、チャンネル権限の取り消し、無効な prompt、AI データ処理の同意の取り消しなど、恒久的または構造的な原因のみです。（複数の宛先へのメール配信では、すべての宛先で失敗した場合のみ配信が失敗となります。一部でも成功すれば送信されます。）1 回の配信実行内ではレンダリング済み Markdown がキャッシュされるため、その実行に対する Temporal の再試行で LLM パイプラインが再実行されることはありません。ただし、新しいスケジュール時刻ごとに新しいレポートが生成されます。

配信開始後

subscriptions-list は新しい行を返します。resource_type: "ai_prompt" と enabled: true が設定されていること、next_delivery_date が未来の日時であること、prompt が送信した内容と一致することを確認してください。最初のスケジュール実行では、planner → HogQL → synthesis のパイプラインが実行され、レンダリング済み Markdown が選択したチャンネルに配信されます。

関連スキル

• managing-subscriptions — insight と dashboard のサブスクリプション、およびそれらに紐づく AI 要約
• building-a-dashboard — ユーザーが文章のレポートではなくグラフを希望する場合にダッシュボードを作成します