Webhook Action

Webhook 有多种类型,按 Action 类型进行分类。例如,定时帖子会触发 scheduled action 的 webhook。更多细节请参阅 webhook 概览。在注册 webhook URL 后,当事件发生时,你的 URL 将会收到一个 POST 请求。该 POST 请求的 body 将包含一个描述事件详情的 JSON 负载。

Scheduled Action

当一条定时帖子被处理(无论成功或失败)并发布到所选社交网络时,你将收到此 webhook 通知。例如,如果你将某条帖子定时在 2026 年 8 月 1 日 12:00 PM 发布,webhook 将在该帖子实际发布时准时发送。只有通过 /post 端点的 scheduleDate 字段安排在未来发布的帖子才会发送 webhook 通知。

Scheduled 事件

{
  "action": "scheduled", // The action taken
  "subAction": "tikTokPublished", // Only present when TikTok video publishing complete
  "created": "2023-01-05T01:18:47Z",
  "code": 200, // HTTP response code
  "refId": "140b8700bd6ade089b242d845e268fb886130c53", // User Reference ID
  "status": "success", // success or error
  "id": "TBAAAqAMMpoweA9wKHUp", // Ayrshare id of post
  "errors": [], // List of errors if any occurred
  "postIds": [
    // Individual successful posts status
    {
      "postUrl": "https://www.facebook.com/102775127855689_361718068618052",
      "platform": "facebook",
      "status": "success",
      "id": "102775127855689_361718068618052"
    }
  ],
  "url": "https://mysite.com/webhook" // Your webhook URL
}

对于立即发布的帖子,你不会收到 webhook 通知,因为 API 会在 JSON 响应中即时返回成功或失败结果。 webhook 通知仅针对定时帖子发送,因为定时帖子是异步处理的,需要额外的通知来告知其状态。

TikTok 发布 Webhook

在通过 Ayrshare 使用 TikTok 时,对于一条定时帖子你可能会收到两种不同的 webhook。如果你的帖子是定时发布而非立即发布,你会先收到标准的 Scheduled Action webhook。这表示媒体已成功提交至 TikTok 进行处理和发布。之后,你还会收到 subAction: tikTokPublished webhook。该 webhook 会在 TikTok 完成媒体处理并公开发布后触发。对于立即发布的帖子和定时发布的帖子,该 webhook 都会触发。在 Ayrshare 控制台中,此事件标记为 tikTok (pub)。

tikTokPublished webhook 只有在媒体被公开发布之后才会发送。如果媒体设置为 private、followers 或 friends,则不会发送该 webhook。如果你未收到 tikTokPublished webhook,且帖子状态仍为 pending,请在 TikTok 手机应用中确认媒体是否已被 TikTok 接受。

当用户的 profile 关联或解绑某个社交网络时的通知。

{
  "account": {
    // Optional: identity of the linked social account. Sent for YouTube only today,
    // not for other platforms.
    "id": "UCxyz123", // Optional: the social network's own account id. For YouTube, the channel id
    "handle": "@socialdept", // Optional: the @ handle, present when the account has one, such as a YouTube custom URL
    "title": "The Social Dept.", // Optional: the social account's own title, such as the YouTube channel name
    "profileUrl": "https://www.youtube.com/@socialdept" // Optional: the public URL of the social account
  },
  "action": "social", // The action taken
  "created": "2023-01-05T01:18:47Z",
  "code": 200, // HTTP response code
  "details": {
    // Optional: sent on unlink, if details are available
    "status": "error",
    "code": 349,
    "message": "Account locked"
  },
  "displayName": "Google Account Name", // If a user account name is present at the social network
  "hookId": "TKLc30192HLGw5UeJ46",
  "platform": "youtube", // The social platform the action occurred on
  "refId": "140b8700bd6ade089b242d845e268fb886130c53", // User Reference ID
  "refreshBy": "2022-11-05T12:21:29Z", // Optional: If type is refresh, the date the social network authorization must be refreshed on the social account linkage page
  "source": "system", // Optional: sent on unlink and refresh. Initiated by "system" or "user".
  "title": "User Profile Name", // The user profile's account title
  "type": "unlink", // Type of action: link, unlink, or refresh
  "url": "https://mysite.com/webhook" // Your webhook URL
}

当 Ayrshare 持有已关联平台的账户级身份信息时（目前仅限 YouTube），会发送 account 对象，并且它会同时包含在 link 和 unlink 操作中。account 中的每个键都是可选的（没有自定义 URL 的 YouTube 频道没有 handle）。当没有可用的身份信息时，account 键会被完全省略，而不是以空值发送，因此在使用某个键之前，请先检查它是否存在。请注意，account.title 是社交账户自身的标题，例如 YouTube 频道名称，而顶层的 title 是你的 Ayrshare 用户资料标题。它们是不同的值。 source 为 system 表示 Ayrshare 自动解绑了该账户,例如社交网络连接不再有效时。我们建议你通知你的用户,以便他们能够继续发布。解绑详情可在 details 字段中查看。系统还会向 Primary Account 邮箱地址或已设置的备用邮箱发送邮件通知。 source 为 user 表示用户主动发起了该操作,例如手动解绑某个账户。用户主动发起的操作不会发送邮件通知。

Messages Action

使用所有 messages 端点和 webhook 需要 Messaging Add-On。对于 Facebook 和 Instagram,当有新的私信 (DM) 到达、被用户读取,或消息上的反应 (reaction) 被创建或删除时,会发送通知。目前 WhatsApp 仅在有新的入站消息被存储时向你注册的 webhook URL 发送通知。 X/Twitter webhook 作为 Enterprise 客户的可选功能提供。关于成为 Enterprise 客户的更多信息,请联系你的客户代表。目前 WhatsApp 不会向你注册的 URL 推送反应事件或投递状态 webhook。已存储的出站消息可能带有取值为 sent、delivered、read 或 failed 的 status —— 详见下文的 WhatsApp Message Status。

多应用共存的 Facebook 主页备用覆盖

除标准 messaging 字段外,Ayrshare 还订阅了 Facebook 的 standby webhook 字段。这意味着,即使同一 Facebook 主页上的另一个应用当前持有 thread control(例如某个聊天机器人平台被设置为主页的 primary receiver,或 Meta 的 Page Inbox 正在处理会话),Messenger 事件仍会送达你的 webhook。这些事件的数据结构没有变化,依然以下面各章节所描述的 messageCreated / messageRead / reactionCreated / messageEdited 负载送达。对于同时安装了其他 Messenger 应用的主页,需要注意以下两点:

入站消息量可能会增加,与此前的行为相比——在订阅 standby 事件之前,这些事件会被静默丢弃。新增的流量对应此前由另一应用处理的、你的主页收到的消息。
**你可能会收到 type: "sent" 的 messageCreated 事件,而这些消息并不是通过 Ayrshare 发送的。**这些是同一主页上另一 Messenger 应用发送消息的回声(Meta 会向每个已订阅的应用推送每条发送消息的副本)。如果你的集成会将出站流量与自己发送历史进行对账,可以使用发送历史来区分自己发送的消息与其他应用发送的消息。

对于仅安装了 Ayrshare(未安装其他 Messenger 应用)的主页,唯一可观察到的变化是新增的 Message Edit 事件——其他内容与此前行为完全一致。

新消息事件

新消息发送或接收时的通知。

当我们无法访问社交网络时,某些字段是可选的。conversationId 和 senderDetails 是在消息到达的那一刻从社交网络解析出来的。当该查询失败时,我们不会扣下这条消息,而是带着我们能解析到的内容照常投递,并设置 connectionDegraded: true。常见的原因是该 profile 的 Instagram 或 Facebook 连接已过期或已失效,但该查询的任何失败都会设置这个标志,包括暂时性的 Graph API 错误。可以通过它是否持续出现来区分:只在单条消息上出现说明只是一次抖动,你无需做任何处理;而在某个 profile 的每条消息上都出现,则说明凭据已失效,只有重新关联才能清除它。

{
  "action": "messages",
  "connectionDegraded": true, // 仅在查询失败时出现
  "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlE...",
  "message": "This is an amazing message",
  "platform": "instagram",
  "recipientId": "17841401430400299",
  "senderId": "17841452212707444",
  "subAction": "messageCreated"
  // conversationId 和 senderDetails 可能不存在
}

当它持续出现时,应将其视为需要重新关联该 profile 社交账户的信号。凭据失效还会导致无法通过 API 回复消息和获取会话历史,因为两者需要同一份凭据。在此期间消息会持续到达,因此不会丢失任何入站数据。通过 Facebook 主页关联的 Instagram 账户依赖该主页的凭据,因此请先重新关联 Facebook,再重新关联 Instagram —— 只重新关联 Instagram 并不能清除该标志。构建集成时,应能容忍任何消息上 conversationId 和 senderDetails 缺失。id、senderId、recipientId 和 platform 始终存在。请注意,message 同样不保证存在,而且这与连接健康状况无关:仅包含附件的消息会携带 attachments 而没有 message 字段。

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-07T11:58:44Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "m_aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA",
  "message": "This is an amazing message",
  "platform": "facebook",
  "recipientId": "7270633706358444",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "scheduleDate": "2024-06-07T11:58:44Z",
  "senderDetails": {
    // recipientDetails if type is sent
    "id": "7270633706358444",
    "picture": "https://scontent-ord5-2.cdninstagram.com/v/t51.jpg",
    "username": "SweetMessage",
    "name": "Sweet"
  },
  "senderId": "17841452212707444",
  "subAction": "messageCreated",
  "timeStamp": 1735189325, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "received", // received, sent, or deleted
  "url": "https://mysite.com/webhook" // Your webhook URL
}

{
  "action": "messages",
  "conversationId": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6MTc4",
  "created": "2024-06-07T11:58:44Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA",
  "message": "This is an amazing message",
  "platform": "instagram",
  "recipientId": "7270633706358444",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "scheduleDate": "2024-06-07T11:58:44Z",
  "senderDetails": {
    // recipientDetails if type is sent
    "id": "7270633706358444",
    "picture": "https://scontent-ord5-2.cdninstagram.com/v/t51.jpg",
    "username": "SweetMessage",
    "name": "Sweet"
  },
  "senderId": "17841452212707444",
  "subAction": "messageCreated",
  "timeStamp": 1735189325, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "received", // received, sent, or deleted
  "url": "https://mysite.com/webhook" // Your webhook URL
}

{
  "action": "messages",
  "attachments": [
    {
      "type": "image",
      "url": "https://images.ayrshare.com/abc123/whatsapp_image_x9aB2pK7.jpg"
    }
  ],
  "conversationId": "14155551234",
  "created": "2026-05-18T17:08:41Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "wamid.HBgLMTQxNTU1NTEyMzQVAgARGBI4OUYxRkExNzE0M0EwQTYwM0EA",
  "message": "Here's the photo you asked for.",
  "platform": "whatsapp",
  "recipientId": "123456789012345",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "senderDetails": {
    "id": "14155551234",
    "name": "Jane Customer"
  },
  "senderId": "14155551234",
  "timeStamp": 1747588121,
  "title": "Primary Profile",
  "url": "https://mysite.com/webhook"
}

对于 WhatsApp,conversationId 与 senderId 是通信对象的电话号码,采用 E.164 仅数字格式。recipientId 是 Meta 分配给你所绑定 WhatsApp 账户的电话号码 ID。启用 Webhook Security 时会包含 timeStamp。在所有网络上,携带媒体的消息都会把媒体放在 attachments 中,正如上面的 WhatsApp 示例所示 —— Facebook 和 Instagram 也不例外。附件类型可为 image、video、audio、document 或 sticker。消息 webhook 从不携带 mediaUrls —— 该字段属于 Scheduled Action 等发布投递后的负载,在那里它报告的是你发送的媒体。

消息已读事件

当消息被收件人读取时的通知。

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-08T23:33:30Z",
  "hookId": "CviPBMXEy3cdJnK0EESd",
  "platform": "facebook",
  "read": 1717889607802,  // UNIX timestamp of when the message was read
  "readerDetails": {
    "name": "John Smith",
    "id": "7101149746568444",
    "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic"
  },
  "recipientId": "106638148652329",
  "refId": "9abf1426d6ce9122ef11c8932",
  "scheduleDate": "2024-06-08T23:33:30Z",
  "senderId": "7101149746568522",
  "subAction": "messageRead",
  "timeStamp": 1717889610, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "read",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

{
  "action": "messages",
  "conversationId": "t_10161117434308938",
  "created": "2024-06-08T23:33:30Z",
  "hookId": "CviPBMXEy3cdJnK0EESd",
  "platform": "instagram",
  "read": {
    "mid": "aWdfZAG1faXRlbToxOkl" // Instagram message ID
  },
  "readerDetails": {
    "name": "John Smith",
    "id": "7101149746568444",
    "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic",
    "username": "johnsmith"
  },
  "recipientId": "106638148652329",
  "refId": "9abf1426d6ce9122ef11c8932",
  "scheduleDate": "2024-06-08T23:33:30Z",
  "senderId": "7101149746568522",
  "subAction": "messageRead",
  "timeStamp": 1717889610, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "read",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

当 Instagram 消息被读取时,webhook 负载会包含一个 mid 字段,用于唯一标识哪条具体消息被读取。对于 Facebook 消息,已读事件是在会话层面通过 conversationId 进行跟踪的。当发生已读事件时,应将该会话中时间戳早于 created(或 read)时间戳的所有消息都视为已被用户读取。

反应的创建与删除事件

当消息上的反应(如点赞)被创建或删除时的通知。

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "platform": "facebook",
  "reaction": "😮",
  "recipientId": "106638148652444",
  "refId": "9abf1426d6ce9432",
  "scheduleDate": "2024-06-06T00:49:18Z",
  "senderId": "7101149746568444",
  "subAction": "reactionCreated", // reactionDeleted if deleted
  "timeStamp": 1717634958, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "reaction",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

{
  "action": "messages",
  "conversationId": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEO",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "platform": "instagram",
  "reaction": "😮",
  "recipientId": "106638148652444",
  "refId": "9abf1426d6ce9432",
  "scheduleDate": "2024-06-06T00:49:18Z",
  "senderId": "7101149746568444",
  "subAction": "reactionCreated", // reactionDeleted if deleted
  "timeStamp": 1717634958, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "reaction",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

消息编辑事件

当用户编辑自己此前发送的消息时的通知。适用于 Facebook 和 Instagram 私信 (DM)。 messageEdit.mid 字段与原始 messageCreated 事件的 id 相同,便于消费者将编辑事件与原始消息进行关联。messageEdit.text 字段包含编辑后的新消息文本。

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "id": "m_xyz...",                    // Message ID — matches the original messageCreated event
  "messageEdit": {
    "mid": "m_xyz...",
    "text": "the edited message text"
  },
  "platform": "facebook",
  "recipientId": "106638148652444",
  "refId": "9abf1426d6ce9432",
  "senderId": "7101149746568444",
  "subAction": "messageEdited",
  "timeStamp": 1717634958,              // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "edit",
  "url": "https://mysite.com/webhook"   // Your webhook URL
}

{
  "action": "messages",
  "conversationId": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEO",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "id": "aWdfZAG1faXRlbToxOkl",
  "messageEdit": {
    "mid": "aWdfZAG1faXRlbToxOkl",
    "text": "the edited message text"
  },
  "platform": "instagram",
  "recipientId": "106638148652444",
  "refId": "9abf1426d6ce9432",
  "senderId": "7101149746568444",
  "subAction": "messageEdited",
  "timeStamp": 1717634958,              // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "edit",
  "url": "https://mysite.com/webhook"   // Your webhook URL
}

WhatsApp Message Status

WhatsApp 在已存储的出站消息上通过单一 status 字段跟踪每条消息的投递状态:sent、delivered、read 或 failed。目前这些更新不会作为独立事件推送到你注册的 webhook URL。如需实时投递状态,请联系你的 Ayrshare 客户代表。

Batch Action

批处理完成并且文件可用时的通知,例如获取所有 user profile。你可以通过 url 字段中的预签名 URL 访问该文件。

Batch 事件

{
  "action": "batch",
  "batchType": "users",
  "created": "2024-01-11T22:00:30Z",
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "source": "user",
  "timeStamp": 1705010424, // Present with Webhook Security
  "title": "Primary Profile",
  "type": "batch",
  "url": "https://storage.googleapis.com/batch.ayrshare.com/users/dfdf92jskd933r/users-batch-2024-01-11-22-00.json",
  "urlExpires": "2024-01-18T22:00:04Z",
  "userCount": 73
}

Feed Action

当为已注册的 RSS 源发现新的 RSS 条目时的通知。注意:当此 Webhook 处于活动状态时,新的 RSS 条目将不会自动发布到社交网络。

Feed 事件

{
    "action": "feed",
    "created": "2023-01-05T01:18:47Z",
    "code": 200,                                          // HTTP response code
    "refId": "140b8700bd6ade089b242d845e268fb886130c53",  // User Reference ID
    "title": "Title of profile if available",             // optional, only if available
    "data": { ... },
    "url": "https://api.myapp.com/Webhook/Ayrshare/Feed"  // Your webhook URL
}

Mentions Action

当你的已关联账户被提及时的通知。适用于 Instagram。

对于 Instagram，注册 mentions webhook 就是接收提及事件所需的全部。无需 Messaging Add-On、消息功能启用或重新关联社交账户。

Ayrshare 会原样转发 Meta 的原生 mention 负载,仅额外添加标准封装字段(action、refId、hookId、url,以及在启用 Webhook Security 时的 timeStamp)、subAction、platform 和 postId。以下示例是 Instagram 的数据形态:media_id,以及当提及发生在评论中时的 comment_id。Facebook 主页提及事件目前不会被投递 —— Ayrshare 会接收 Meta 的通知但不会转发到你的 webhook。目前仅投递 Instagram 提及事件,因此该 action 上的 platform 始终为 instagram。 postId 遵循与 Comments Action 相同的规则,并且在提及事件上通常不存在:提及一般发生在他人的帖子上,而那些帖子没有 Ayrshare id。只有当提及发生在你通过 Ayrshare 发布的帖子上时,它才会出现。

Mention 事件(Instagram)

{
  "action": "mentions",
  "subAction": "mention",
  "platform": "instagram",            // The social network the mention came from
  "postId": "TBAAAqAMMpoweA9wKHUp",   // Ayrshare post id; absent unless you published the post
  "media_id": "17900000000000000",    // Meta media the mention occurred on
  "comment_id": "17900000000000001",  // Present when the mention is in a comment
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1705010424,             // Present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Mentions"  // Your webhook URL
}

Comments Action

当你已关联的内容上有新评论时的通知。适用于 Facebook 和 Instagram。

对于 Instagram，注册 comments webhook 就是接收评论事件所需的全部。无需 Messaging Add-On、消息功能启用或重新关联社交账户。对于 Facebook，仅当档案启用了消息功能（Messaging Add-On）时才会投递评论事件——仅注册 comments webhook 是不够的。无需重新关联 Facebook 主页。

Ayrshare 会原样转发 Meta 的原生 comment 负载,仅额外添加标准封装字段(action、refId、hookId、url,以及在启用 Webhook Security 时的 timeStamp)、subAction、platform 和 postId。以下示例是 Instagram 的数据形态。Facebook 评论以 Page feed change 形式送达,字段名不同(例如 comment_id、post_id、message 和 from.name);完整字段集请参考 Meta 的 webhooks 文档。由于两个网络都会投递到同一个 comments 端点,请根据 platform(instagram 或 facebook)进行分支,而不是通过出现的字段名去推断来源网络。

将评论与你创建的帖子关联起来

postId 是评论所在帖子的 Ayrshare id —— 与你创建帖子时发布帖子返回的 id 相同,也是获取帖子和帖子分析所接受的那个 id。它的存在使你无需自己维护一份原生 id 的映射表,就能把评论匹配到你自己的帖子。它是尽力而为的,在无法确定时会被省略。请把缺失的 postId 理解为“这条评论不在我发布的帖子上”,而绝不要视为错误。它在以下情况下不会出现:

帖子不是通过 Ayrshare 发布的。 你已关联账户上的所有内容都会触发评论事件,包括直接在 Instagram 或 Facebook 应用中创建的帖子。这些帖子根本没有 Ayrshare id —— 无从恢复。
帖子发布于该字段上线之前。 关联数据是在发布时记录的,不会回填,因此你较早帖子上的评论不会携带 postId。
帖子由另一个 User Profile 发布。 多个 profile 可以关联到同一个 Facebook 主页或 Instagram 账户并都收到评论事件,但只有实际发布该帖子的 profile 才会被告知其 id。

postId 是 Ayrshare 的帖子 id,而不是社交网络的。同一帖子在社交网络上自己的 id 仍在原来的位置 —— Instagram 上是 media.id,Facebook 上是 post_id。

Comment 事件(Instagram)

{
  "action": "comments",
  "subAction": "comment",
  "platform": "instagram",             // The social network the comment came from
  "postId": "TBAAAqAMMpoweA9wKHUp",    // Ayrshare post id; absent unless you published the post
  "id": "17900000000000002",           // Comment ID
  "text": "Great post!",
  "from": {
    "id": "1234567890",
    "username": "alice"
  },
  "media": {
    "id": "17900000000000000",         // ID of the commented media
    "media_product_type": "FEED"       // e.g. FEED, REELS, STORY
  },
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1705010424,             // Present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Comments"  // Your webhook URL
}

Automations Action

当自动化 (automation) 为用户触发一个 webhook action 时的通知,例如评论或 DM 自动回复触发器。 automations action 上会发送两种事件类型,通过 type 字段进行区分。完整的字段参考请参见 webhook 事件。

`type`	发送时机
`automation.triggered`	自动化的 `fire_webhook` action 运行时。当派发被限流或该 action 被去重时不会发送
`automation.completed`	派发达到终态时。默认关闭:仅当自动化的 `fire_webhook` action 设置了 `"sendCompletedEvent": true` 时才发送

Automation Triggered 事件

{
  "action": "automations",
  "type": "automation.triggered",
  "automationId": "a1B2c3D4",
  "triggerId": "t9X8y7Z6",
  "trigger": "comment_keyword",        // The trigger type that fired the automation (varies by automation)
  "platform": "instagram",
  "recipientId": "17841400000000000",
  "recipientUsername": "alice",        // null if unavailable
  "keyword": "INFO",                   // null if not keyword-triggered; the emoji for dm_reaction
  "activityId": "a1B2c3D4:t9X8y7Z6:comment.received:17912345678901234", // Matches the row in GET /automations/:id/activity
  "actionId": "act_wh_1",              // The fire_webhook action that sent this; matches actionResults[].actionId
  "eventId": "comment.received:17912345678901234",
  "commentId": "17912345678901234",    // null for DM-driven triggers
  "commentText": "INFO please",        // DM text for dm_keyword, the emoji for dm_reaction, null when there is none
  "postId": "17895695668004550",       // null unless the engagement was on a post or reel
  "storyId": null,                     // null unless the engagement was on a story
  "timestamp": "2026-05-27T22:00:30Z", // When the automation fired (ISO 8601)
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1705010424,             // Unix timestamp, present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Automations"  // Your webhook URL
}

Automation Completed 事件

{
  "action": "automations",
  "type": "automation.completed",
  "automationId": "a1B2c3D4",
  "triggerId": "t9X8y7Z6",
  "trigger": "comment_keyword",
  "platform": "instagram",
  "recipientId": "17841400000000000",
  "activityId": "a1B2c3D4:t9X8y7Z6:comment.received:17912345678901234", // Join key; matches automation.triggered when one was sent
  "eventId": "comment.received:17912345678901234",
  "status": "sent",                    // sent, failed, rate_limited, deduplicated, skipped, or auth_error
  "actionResults": [                   // Empty when rate_limited, deduplicated, or failed after the retry limit
    { "actionId": "act_dm_1", "type": "send_dm", "status": "sent", "errorDetails": null },
    { "actionId": "act_wh_1", "type": "fire_webhook", "status": "sent", "errorDetails": null }
  ],
  "errorDetails": null,                // Reason when skipped, rate_limited, or failed after the retry limit
  "timestamp": "2026-05-27T22:00:58Z",
  "hookId": "Kq2LmN8pR4tV6wXyZ1aB",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "timeStamp": 1705010452,
  "url": "https://api.myapp.com/Webhook/Ayrshare/Automations"
}

Demo Action

针对 Demo User Profile 生命周期事件的通知。Demo User Profile 仅在 Enterprise plan 上可用;如需了解更多信息,请联系我们。 demo action 上会发送两种事件类型,通过 type 字段进行区分:

upgradeWarning —— 在 Demo User Profile 自动转换为标准 User Profile 之前两天发送,以便你提示用户继续使用或移除该 profile。
upgrade —— 在转换发生时发送。

Demo Upgrade Warning 事件

{
  "action": "demo",
  "type": "upgradeWarning",
  "demoExpires": "2026-08-27T09:57:00.000Z",  // profile 转换的时间(ISO 8601)
  "daysUntilUpgrade": 2,
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1787734624,             // Unix 时间戳(2026-08-26),启用 Webhook Security 时存在
  "url": "https://api.myapp.com/Webhook/Ayrshare/Demo"  // Your webhook URL
}

Demo Upgrade 事件

{
  "action": "demo",
  "type": "upgrade",
  "upgradedAt": "2026-08-28T08:57:04.000Z",  // profile 完成转换的时间(ISO 8601)
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1787907424,             // Unix 时间戳(2026-08-28),启用 Webhook Security 时存在
  "url": "https://api.myapp.com/Webhook/Ayrshare/Demo"  // Your webhook URL
}

Suspended Action

当 User Profile 被暂停或重新激活时的通知。暂停可能源于社交网络自身的执行策略(例如 Facebook 的身份验证要求)、速率限制保护,或计费问题。在 profile 处于暂停状态期间,针对该 profile 的 API 调用会返回 HTTP 403。 suspended action 上会发送两种事件类型,通过 type 字段进行区分:

suspend —— 在 profile 被暂停时发送。请为该 profile 暂停发帖及其他活动,直到其被重新激活。
unsuspend —— 在 profile 被重新激活时发送。

只有当 profile 的整体暂停状态发生变化时才会发送事件。一个 profile 可能同时因多种原因被暂停:如果在 profile 已处于暂停状态时又新增了一个原因,或多个原因中的某一个被解除但另一个仍然适用,都不会发送事件 —— profile 仍保持暂停状态,下一次事件将是最后一个原因被清除时的 unsuspend。要随时查看当前的暂停状态,请使用 Get Profiles 并附带 include=suspension。由平台触发的暂停通常会先伴随一条针对受影响社交网络的 Social Action 解绑事件。此类暂停只能在源头解除 —— 例如 Facebook 的身份验证必须由 Page 管理员在 Facebook 应用中完成 —— 之后 profile 才能被重新激活,并重新绑定该社交网络。

Suspend 事件

{
  "action": "suspended",
  "type": "suspend",
  "reason": "Confirm your identity before you can publish as this Page.", // 由平台或 Ayrshare 报告的原因;如不可用则为 null
  "platform": "facebook",              // 触发该暂停的社交网络;如非平台触发则为 null
  "origin": "policy",                  // 导致 profile 被暂停的来源:policy、payment、rateLimit、manual、report 或 subscription;如不可用则为 null
  "suspendedAt": "2026-08-13T20:31:41.128Z", // 暂停发生的时间(ISO 8601);如不可用则为 null
  "unsuspendAt": null,                 // 已知的自动重新激活计划时间(ISO 8601)
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1786731101,             // Unix 时间戳,启用 Webhook Security 时存在
  "url": "https://api.myapp.com/Webhook/Ayrshare/Suspended"  // Your webhook URL
}

Unsuspend 事件

{
  "action": "suspended",
  "type": "unsuspend",
  "reason": null,
  "platform": null,
  "origin": null,
  "suspendedAt": null,
  "unsuspendAt": null,
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1786988742,             // Unix 时间戳,启用 Webhook Security 时存在
  "url": "https://api.myapp.com/Webhook/Ayrshare/Suspended"  // Your webhook URL
}

暂停事件是针对状态发生变化的 profile 发送的。你也可以随时通过 Get Profiles 并附带 include=suspension 查询暂停状态,它会返回 isSuspended、reason、suspendedAt、unsuspendAt 和 suspensionCount。

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Scheduled Action

Scheduled 事件

TikTok 发布 Webhook

Messages Action

多应用共存的 Facebook 主页备用覆盖

新消息事件

消息已读事件

反应的创建与删除事件

消息编辑事件

WhatsApp Message Status

Batch Action

Batch 事件

Feed Action

Feed 事件

Mentions Action

Mention 事件(Instagram)

Comments Action

将评论与你创建的帖子关联起来

Comment 事件(Instagram)

Automations Action

Automation Triggered 事件

Automation Completed 事件

Demo Action

Demo Upgrade Warning 事件

Demo Upgrade 事件

Suspended Action

Suspend 事件

Unsuspend 事件

​Scheduled Action

​Scheduled 事件

​TikTok 发布 Webhook

​Social Action

​Social Action 事件

​Messages Action

​多应用共存的 Facebook 主页备用覆盖

​新消息事件

​消息已读事件

​反应的创建与删除事件

​消息编辑事件

​WhatsApp Message Status

​Batch Action

​Batch 事件

​Feed Action

​Feed 事件

​Mentions Action

​Mention 事件(Instagram)

​Comments Action

​将评论与你创建的帖子关联起来

​Comment 事件(Instagram)

​Automations Action

​Automation Triggered 事件

​Automation Completed 事件

​Demo Action

​Demo Upgrade Warning 事件

​Demo Upgrade 事件

​Suspended Action

​Suspend 事件

​Unsuspend 事件

Scheduled Action

Scheduled 事件

TikTok 发布 Webhook

Social Action

Social Action 事件

Messages Action

多应用共存的 Facebook 主页备用覆盖

新消息事件

消息已读事件

反应的创建与删除事件

消息编辑事件

WhatsApp Message Status

Batch Action

Batch 事件

Feed Action

Feed 事件

Mentions Action

Mention 事件(Instagram)

Comments Action

将评论与你创建的帖子关联起来

Comment 事件(Instagram)

Automations Action

Automation Triggered 事件

Automation Completed 事件

Demo Action

Demo Upgrade Warning 事件

Demo Upgrade 事件

Suspended Action

Suspend 事件

Unsuspend 事件