> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook Action
> Webhook 的 Action 与事件
Webhook 有多种类型,按 Action 类型进行分类。
例如,定时帖子会触发 `scheduled` action 的 webhook。
更多细节请参阅 [webhook 概览](/apis/webhooks/overview)。
在注册 webhook URL 后,当事件发生时,你的 URL 将会收到一个 POST 请求。
该 POST 请求的 body 将包含一个描述事件详情的 JSON 负载。
## Scheduled Action
当一条定时帖子被处理(无论成功或失败)并发布到所选社交网络时,你将收到此 webhook 通知。
例如,如果你将某条帖子定时在 2026 年 8 月 1 日 12:00 PM 发布,webhook 将在该帖子实际发布时准时发送。
只有通过 [/post](/apis/post/post) 端点的 `scheduleDate` 字段安排在未来发布的帖子才会发送 webhook 通知。
### Scheduled 事件
```json theme={"system"}
{
"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 只有在[媒体被公开发布](/apis/post/social-networks/tiktok#visibility-options)之后才会发送。
如果媒体设置为 private、followers 或 friends,则不会发送该 webhook。
如果你未收到 `tikTokPublished` webhook,且帖子状态仍为 `pending`,请在 TikTok 手机应用中确认媒体是否已被 TikTok 接受。
## Social Action
当用户的 profile 关联或解绑某个社交网络时的通知。
### Social Action 事件
```json theme={"system"}
{
"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 邮箱地址或已设置的[备用邮箱](/multiple-users/manage-user-profiles#alternative-emails-for-alerts)发送邮件通知。
`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 事件](#message-edit-event)——其他内容与此前行为完全一致。
### 新消息事件
新消息发送或接收时的通知。
```json Facebook New Message theme={"system"}
{
"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
}
```
```json Instagram New Message theme={"system"}
{
"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
}
```
### 消息已读事件
当消息被收件人读取时的通知。
```json Facebook Read theme={"system"}
{
"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
}
```
```json Instagram Read theme={"system"}
{
"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`)时间戳的所有消息都视为已被用户读取。
### 反应的创建与删除事件
当消息上的反应(如点赞)被创建或删除时的通知。
```json Facebook Reaction theme={"system"}
{
"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
}
```
```json Instagram Reaction theme={"system"}
{
"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` 字段包含编辑后的新消息文本。
```json Facebook Message Edit theme={"system"}
{
"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
}
```
```json Instagram Message Edit theme={"system"}
{
"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](/apis/user/batch-all-users)。你可以通过 `url` 字段中的预签名 URL 访问该文件。
### Batch 事件
```json theme={"system"}
{
"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 事件
```json theme={"system"}
{
"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)
```json theme={"system"}
{
"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)
```json theme={"system"}
{
"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 事件
```json theme={"system"}
{
"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
}
```