creating-ai-subscription

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating a prompt subscription

创建提示词订阅

When to use this

适用场景

A subscription delivers a PostHog report to email or Slack on a recurring schedule. There are three kinds, distinguished by which field you set — the kind is derived and returned as the read-only

resource_type

insight
— periodic snapshots of one existing insight (
```
resource_type: "insight"
```
)
dashboard
— periodic snapshots of a dashboard's tiles (
```
resource_type: "dashboard"
```
)
prompt
— a recurring AI-generated report from a free-text prompt: an LLM plans and runs HogQL over the project's data and synthesizes a fresh markdown report each tick (
```
resource_type: "ai_prompt"
```
)

Use this skill for the prompt kind — i.e. when the user wants a recurring AI summary of X (on any cadence — daily, weekly, monthly, yearly) rather than a recurring snapshot of one existing insight/dashboard, or a single one-off report. Pick a prompt subscription when the value is the analysis itself (the LLM deciding what to query and writing it up), not a fixed chart they already built. For an insight/dashboard subscription, set

insight

dashboard

instead of

prompt

and the AI gates below don't apply.

This skill covers creating the subscription. Once it exists you manage its lifecycle with the same

subscriptions-*

tools (see below): list it, edit/disable/ re-enable it, send a test delivery, or delete it.

订阅功能会按周期性计划将PostHog报告发送至邮箱或Slack。订阅分为三类，由设置的字段区分，类型会自动推导并作为只读字段

resource_type

insight
— 现有单个洞察的定期快照（
```
resource_type: "insight"
```
）
dashboard
— 仪表盘组件的定期快照（
```
resource_type: "dashboard"
```
）
prompt
— 基于自由文本提示词生成的周期性AI报告：LLM会规划并运行针对项目数据的HogQL查询，每次调度时生成全新的markdown报告（
```
resource_type: "ai_prompt"
```
）

本技能适用于prompt类型的订阅——即当用户需要按任意周期（每日、每周、每月、每年）获取X的周期性AI摘要，而非现有洞察/仪表盘的定期快照或一次性报告时。当价值核心在于分析本身（由LLM决定查询内容并撰写报告），而非用户已构建的固定图表时，请选择提示词订阅。若要创建洞察/仪表盘订阅，请设置

insight

dashboard

字段而非

prompt

，且以下AI相关限制不适用。

本技能涵盖订阅的创建流程。订阅创建完成后，可使用相同的

subscriptions-*

工具管理其生命周期（见下文）：列出订阅、编辑/禁用/重新启用、发送测试推送或删除订阅。

Tools

工具

Tool	Purpose
`posthog:subscriptions-create`	Create the recurring prompt subscription
`posthog:subscriptions-list`	Confirm it landed; inspect existing subscriptions
`posthog:subscriptions-partial-update`	Edit, disable ( `enabled: false` ), or re-enable it
`posthog:subscriptions-test-delivery-create`	Send an immediate test delivery to its target(s)
`posthog:subscriptions-delete`	Soft-delete it (stops all future deliveries)
`posthog:integrations-list`	Find a Slack `integration_id` (filter `kind=slack` )
`posthog:integrations-channels-retrieve`	List a Slack integration's channels (id + name)

工具名称	用途
`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 + 名称）

What you need before calling

调用前需满足的条件

The endpoint enforces three create-time gates and will return 400 if any fails:

PostHog Cloud, or
DEBUG=true
— self-hosted production deployments are not eligible (the LLM call routes through a PostHog-managed key).
Org-level "AI data processing approved" — must be toggled on in
```
Org settings → Data → AI data processing
```
. The user must opt in to AI features for the organization first.
Prompt subscriptions enabled for the organization — a PostHog-managed rollout flag. If it's off, the org has not been granted access yet; tell the user to reach out to PostHog to enable it (there is no self-serve toggle).

If any of the three is missing, stop and tell the user which one to fix — re-calling the tool will not help.

Your access token also needs the query:read
scope in addition to

subscription:write

: a prompt subscription runs LLM-generated HogQL over the project's data, so the backend requires query access to create, edit/re-enable, test-deliver, or delete one. A

subscription:write

-only token is rejected with a 403.

接口在创建时会检查三个条件，若任一条件不满足则返回400错误：

PostHog Cloud环境，或
DEBUG=true
— 自托管生产环境无法使用此功能（LLM调用需通过PostHog管理的密钥路由）。
组织级已开启“AI数据处理权限” — 需在
```
组织设置 → 数据 → AI数据处理
```
中开启该选项。用户需先为组织选择启用AI功能。
组织已启用提示词订阅功能 — 这是PostHog管理的灰度发布功能。若未开启，说明该组织尚未获得访问权限；请告知用户联系PostHog开启（无自助开启开关）。

若任一条件不满足，请停止操作并告知用户需要修复的内容——重新调用工具无法解决问题。

你的访问令牌除了

subscription:write

权限外，还需要**

query:read

**权限：提示词订阅会运行LLM生成的HogQL查询项目数据，因此后端要求具备查询权限才能创建、编辑/重新启用、测试推送或删除订阅。仅拥有

subscription:write

权限的令牌会被拒绝并返回403错误。

Required arguments

必填参数

yaml

prompt: "..."                         # ≤4000 chars; setting this (with no insight/dashboard) makes it a prompt sub → resource_type "ai_prompt"
target_type: "email" | "slack"        # webhook is rejected for prompt subs
target_value: "..."                   # comma-separated emails, or "<channel_id>|<channel_name>"
frequency: "daily" | "weekly" | "monthly" | "yearly"
interval: 1                            # 1 = every tick; 2 = every other tick; etc.
start_date: "2026-09-15T09:00:00Z"   # anchors the recurrence + time-of-day; need not be in the future — the scheduler delivers the next occurrence
title: "..."                          # display name in the subscriptions list

There is no

resource_type

argument to send — the kind is derived from which field you set (

prompt

⇒ AI report) and returned as the read-only

resource_type

yaml

prompt: "..."                         # 最多4000字符；设置此字段（且不设置insight/dashboard）会创建提示词订阅 → resource_type为"ai_prompt"
target_type: "email" | "slack"        # 提示词订阅不支持webhook类型的目标
target_value: "..."                   # 逗号分隔的邮箱地址，或"<channel_id>|<channel_name>"格式
frequency: "daily" | "weekly" | "monthly" | "yearly"
interval: 1                            # 1表示每次调度都执行；2表示每隔一次调度执行；以此类推
start_date: "2026-09-15T09:00:00Z"   # 确定 recurrence 规则和执行时间；无需设置为未来时间——调度器会执行下一次符合条件的任务
title: "..."                          # 订阅列表中显示的名称

无需传入

resource_type

参数——订阅类型会自动推导（设置

prompt

字段则为AI报告），并作为只读字段

resource_type

返回。

Optional arguments

可选参数

yaml

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 # cap total deliveries
until_date: '2026-12-31T00:00:00Z' # stop on/before this date
integration_id: 42 # Slack only — required; from integrations-list (see "Slack target")

yaml

byweekday: ['monday', 'wednesday'] # 仅适用于每周频率——设置规则触发的星期几
bysetpos: 1 # 最适用于每月频率；需配合byweekday使用——例如 byweekday:['monday']+bysetpos:-1 = 当月最后一个周一
count: 10 # 设置最大推送次数
until_date: '2026-12-31T00:00:00Z' # 设置停止推送的日期（在此日期当天或之前停止）
integration_id: 42 # 仅适用于Slack目标——必填；通过integrations-list工具获取（见“Slack目标”部分）

Slack target

Slack目标

target_value

must be

<channel_id>|<channel_name>

(the format the integration returns). Build it in three steps:

```
posthog:integrations-list
```
filtered by
```
kind=slack
```
→ pick the Slack integration's
```
id
```
.
```
posthog:integrations-channels-retrieve
```
with that
```
id
```
→ pick a channel; it returns each channel's
```
id
```
and
```
name
```
, which you assemble into
```
target_value
```
as
```
<id>|<name>
```
.
Pass that integration's
```
id
```
as
```
integration_id
```
— the subscription is pinned to one specific Slack integration so reconnections elsewhere don't accidentally re-route deliveries.

target_value

必须为

<channel_id>|<channel_name>

格式（集成返回的格式）。可通过以下三步构建：

使用
```
posthog:integrations-list
```
工具并筛选
```
kind=slack
```
→ 获取Slack集成的
```
id
```
。
使用该
```
id
```
调用
```
posthog:integrations-channels-retrieve
```
工具 → 选择一个频道；工具会返回每个频道的
```
id
```
和
```
name
```
，将其组合为
```
<id>|<name>
```
格式作为
```
target_value
```
。
将该集成的
```
id
```
作为
```
integration_id
```
传入——订阅会绑定到指定的Slack集成，因此其他位置的重新连接不会意外更改推送路由。

Examples

示例

Weekly Monday-morning AI summary by email

每周一上午通过邮箱发送AI摘要

yaml

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

yaml

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

Daily Slack report at 9am

每日上午9点通过Slack发送报告

yaml

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'

yaml

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>格式；仅channel_id会被实际使用，name仅用于显示
integration_id: 42
frequency: daily
interval: 1
start_date: '2026-09-15T09:00:00Z'
title: 'Daily onboarding watch'

Pitfalls

注意事项

The kind is immutable. It's derived from which relation is set, so you can't flip an insight or dashboard sub into a prompt sub after the fact (or vice versa) — a PATCH that adds a
```
prompt
```
to an insight sub is rejected. Pick the right kind at create time.
Re-enabling a previously auto-disabled prompt sub has two preconditions, both enforced on the PATCH: (1) a valid
```
prompt
```
— already persisted on the row, or a new one in the PATCH body (so bare
```
{"enabled": true}
```
works when the stored prompt is still valid, but is rejected when the disable cause was an invalid prompt until you supply a good one); and (2) the original creator is still an active user — if that account was deactivated the sub cannot be re-enabled at all (no prompt will help; re-create it instead).
next_delivery_date
is server-computed from the rrule. Don't try to set it manually — it's read-only. The first delivery fires at the first
```
start_date
```
occurrence that is at least a short buffer (currently ~15 minutes) in the future, so a
```
start_date
```
only seconds ahead rolls to the next occurrence.
Transient send failures retry; only permanent failures auto-disable. A transient failure (Slack rate limit, SMTP blip, network) fails that delivery and is retried by Temporal within the run, then re-fires on the next scheduled tick — it does not auto-disable the subscription, so a persistently-failing channel will keep retrying every tick until you fix it. Only permanent/structural causes auto-disable: a disconnected Slack integration, a revoked channel permission, an invalid prompt, or revoked AI data-processing consent. (For multi-recipient email, a delivery only fails when every recipient fails; partial successes still send.) Within a single delivery run the rendered markdown is cached, so Temporal retries of that run don't re-run the LLM pipeline — but each new scheduled tick generates a fresh report.

订阅类型不可变更。类型由设置的关联字段推导而来，因此无法将洞察或仪表盘订阅转换为提示词订阅（反之亦然）——若向洞察订阅的PATCH请求中添加
```
prompt
```
字段会被拒绝。请在创建时选择正确的订阅类型。
重新启用之前自动禁用的提示词订阅需满足两个前置条件，均会在PATCH请求时检查：(1) 有效的
```
prompt
```
字段——已存储在记录中，或在PATCH请求体中提供新的有效提示词（因此当存储的提示词仍然有效时，仅发送
```
{"enabled": true}
```
即可生效，但如果禁用原因是提示词无效，则必须提供有效的提示词才能重新启用）；(2) 原始创建者仍为活跃用户——若该账户已被停用，则无法重新启用订阅（任何提示词都无法解决；请重新创建订阅）。
next_delivery_date
由服务器根据rrule计算得出。请勿尝试手动设置——该字段为只读。第一次推送会在
```
start_date
```
之后的第一个符合条件的时间点触发，且该时间点需至少在当前时间之后一段缓冲时间（目前约15分钟），因此若
```
start_date
```
仅比当前时间晚几秒，则会自动顺延至下一个符合条件的时间点。
临时推送失败会重试；仅永久失败会自动禁用订阅。临时失败（Slack限流、SMTP故障、网络问题）会导致本次推送失败，由Temporal在任务运行期间重试，然后在下一次调度时重新触发——这不会自动禁用订阅，因此持续失败的频道会在每次调度时重试，直到问题被修复。仅永久/结构性问题会导致自动禁用：Slack集成断开、频道权限被撤销、提示词无效或AI数据处理权限被撤销。（对于多收件人邮箱，仅当所有收件人都失败时才会判定推送失败；部分成功仍会发送。）在单次推送运行中，渲染后的markdown会被缓存，因此Temporal的重试不会重新运行LLM流程——但每次新的调度都会生成全新的报告。

After it lands

创建完成后

subscriptions-list

will return the new row. Confirm

resource_type: "ai_prompt"

enabled: true

next_delivery_date

is in the future, and

prompt

matches what you sent. The first scheduled tick will run the planner → HogQL → synthesis pipeline and email/Slack the rendered markdown.

使用

subscriptions-list

工具会返回新创建的订阅记录。请确认

resource_type: "ai_prompt"

、

enabled: true

、

next_delivery_date

为未来时间，且

prompt

字段与你传入的内容一致。第一次调度时会执行规划→HogQL查询→合成流程，并将渲染后的markdown内容通过邮箱/Slack发送。