Webhook Action - Ayrshare API Documentation

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 关联或解绑某个社交网络时的通知。

{
  "action": "social", // The action taken
  "created": "2023-01-05T01:18:47Z",
  "code": 200, // HTTP response code
  "details": {
    // Optional: if details available
    "status": "error",
    "code": 349,
    "message": "Account locked"
  },
  "displayName": "Instagram Title", // If a user account name is present at the social network
  "hookId": "TKLc30192HLGw5UeJ46",
  "platform": "instagram", // The social platform the action occured
  "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", // Initiated by "system" or "user".
  "title": "User Profile Name", // The user profile's account title
  "type": "link", // Type of action: link, unlink, or refresh
  "url": "https://mysite.com/webhook" // Your webhook URL
}

source 为 system 表示 Ayrshare 自动解绑了该账户,例如社交网络连接不再有效时。我们建议你通知你的用户,以便他们能够继续发布。解绑详情可在 details 字段中查看。系统还会向 Primary Account 邮箱地址或已设置的备用邮箱发送邮件通知。 source 为 user 表示用户主动发起了该操作,例如手动解绑某个账户。用户主动发起的操作不会发送邮件通知。

Messages Action

使用所有 messages 端点和 webhook 需要 Messaging Add-On。当有新的私信 (DM) 到达、被用户读取,或消息上的反应 (reaction) 被创建或删除时的通知,仅适用于 Facebook 和 Instagram。 X/Twitter webhook 作为 Enterprise 客户的可选功能提供。关于成为 Enterprise 客户的更多信息,请联系你的客户代表。

多应用共存的 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 事件——其他内容与此前行为完全一致。

新消息事件

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

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-07T11:58:44Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "m_aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA",
  "mediaUrls": [],
  "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",
  "mediaUrls": [],
  "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",
  "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",
  "mediaUrls": [],
  "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",
  "mediaUrls": [],
  "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
}

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

当你的已关联账户被提及时的通知。适用于 Facebook 和 Instagram。 Ayrshare 会原样转发 Meta 的原生 mention 负载,仅额外添加标准封装字段(action、refId、hookId、url,以及在启用 Webhook Security 时的 timeStamp)和 subAction。以下示例是 Instagram 的数据形态:media_id,以及当提及发生在评论中时的 comment_id。Facebook 提及事件以 Meta 原生的 Page mention change 形式送达,字段集与 Instagram 示例不同;完整字段集请参考 Meta 的 webhooks 文档。

Mention 事件(Instagram)

{
  "action": "mentions",
  "subAction": "mention",
  "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。 Ayrshare 会原样转发 Meta 的原生 comment 负载,仅额外添加标准封装字段(action、refId、hookId、url,以及在启用 Webhook Security 时的 timeStamp)和 subAction。以下示例是 Instagram 的数据形态。Facebook 评论以 Page feed change 形式送达,字段名不同(例如 comment_id、post_id、message 和 from.name);完整字段集请参考 Meta 的 webhooks 文档。

Comment 事件(Instagram)

{
  "action": "comments",
  "subAction": "comment",
  "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 自动回复触发器。

Automation 事件

{
  "action": "automations",
  "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
  "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
}

​Scheduled Action

​Scheduled 事件

​TikTok 发布 Webhook

​Social Action

​Social Action 事件

​Messages Action

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

​新消息事件

​消息已读事件

​反应的创建与删除事件

​消息编辑事件

​Batch Action

​Batch 事件

​Feed Action

​Feed 事件

​Mentions Action

​Mention 事件(Instagram)

​Comments Action

​Comment 事件(Instagram)

​Automations Action

​Automation 事件

Scheduled Action

Scheduled 事件

TikTok 发布 Webhook

Social Action

Social Action 事件

Messages Action

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

新消息事件

消息已读事件

反应的创建与删除事件

消息编辑事件

Batch Action

Batch 事件

Feed Action

Feed 事件

Mentions Action

Mention 事件(Instagram)

Comments Action

Comment 事件(Instagram)

Automations Action

Automation 事件