> ## 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 動作
> Webhook 動作與事件
Webhook 有多種類型，並依據動作類型（Action）分類。
例如，一則排程貼文會觸發 `scheduled` 動作的 Webhook。
更多細節請參閱 [Webhook 概觀](/apis/webhooks/overview)。
在註冊 Webhook URL 之後，當事件發生時，你會收到一個 POST 請求送到該 URL。
該 POST 請求會包含含有事件詳細內容的 JSON payload。
## Scheduled 動作
當排程貼文被處理時（無論成功或失敗）並發布至所選的社群網路時，你會收到此 Webhook 通知。
例如，若你將貼文排程於 2026 年 8 月 1 日中午 12:00，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 動作** Webhook。
這代表媒體已成功送至 TikTok，等待處理與發布。
之後，你會收到 `subAction: tikTokPublished` Webhook。
一旦 TikTok 完成媒體的處理且媒體被公開後，即會觸發此 Webhook。
此 Webhook 會針對即時貼文與排程貼文皆會觸發。
在 Ayrshare 控制台中，此事件會標示為 **tikTok (pub)**。
`tikTokPublished` Webhook 在[媒體被設為公開](/apis/post/social-networks/tiktok#visibility-options)前不會發送。
若媒體設為 private、followers 或 friends，則不會發送此 Webhook。
若你未收到 `tikTokPublished` Webhook 且貼文狀態仍為 `pending`，請至 TikTok 行動應用程式確認該媒體是否已被 TikTok 接受。
## Social 動作
當使用者 Profile 連結或解除連結社群網路時的通知。
### Social 動作事件
```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 動作
存取所有 messages 端點與 Webhook 需要 Messaging 附加功能。
當有新的私訊到達、被使用者已讀，或訊息上有反應（reaction）建立或刪除時的通知，僅支援 Facebook 與 Instagram。
X/Twitter Webhook 是 Enterprise 客戶的可選項目。
如需成為 Enterprise 客戶的相關資訊，請聯絡你的專屬帳號代表。
### 針對安裝了多個 App 的 Facebook 粉絲專頁的 Standby 涵蓋
Ayrshare 除了標準的 messaging 欄位外，也訂閱了 Facebook 的 `standby` Webhook 欄位。這代表即使**同一個 Facebook 粉絲專頁上有另一個 App 目前擁有對話控制權**——例如某個 chatbot 平台被設為你的粉絲專頁主要接收者，或 Meta 的 Page Inbox 正在主動處理該對話——Messenger 事件仍會送到你的 Webhook。
這些事件的資料結構並無變更。它們會以下方章節所描述的相同 `messageCreated` / `messageRead` / `reactionCreated` / `messageEdited` payload 送達。若粉絲專頁上另有 Messenger App 存在，需注意兩點：
* **進入的訊息量可能會增加**，相較於先前這些 standby 事件在未訂閱時會被靜默丟棄。新的流量代表你的粉絲專頁曾收到、但由其他 App 處理的訊息。
* **你可能會收到 `type: "sent"` 的 `messageCreated` 事件，但這些訊息並非透過 Ayrshare 發出。** 這些是同一粉絲專頁上另一個 Messenger App 所發送訊息的回聲（Meta 會將每次發送的副本傳送給所有已訂閱的 App）。若你的整合會依據自身發送記錄核對外送流量，可利用該記錄來區分你發送的訊息與其他 App 發送的訊息。
對於只安裝 Ayrshare（沒有其他 Messenger App）的粉絲專頁而言，唯一可觀察到的變化是新的[訊息編輯事件](#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 payload 會包含一個 `mid` 欄位，用來唯一識別哪一則訊息被已讀。
對於 Facebook 訊息，訊息已讀是以對話層級透過 `conversationId` 進行追蹤。
當已讀事件發生時，該對話中時間戳早於 `created`（或 `read`）時間戳的所有訊息，都應被視為已被使用者讀取。
### 反應建立與刪除事件
當訊息上有反應（例如 like）被建立或刪除時的通知。
```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 私訊。
`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 動作
當某個批次完成處理且檔案已可存取時的通知，例如[取得所有 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 動作
當已註冊的 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 動作
當你已連結的帳號被提及（mention）時的通知。支援 Facebook 與 Instagram。
Ayrshare 會將 Meta 原生的 mention payload 原樣轉發，僅額外加上標準的封包欄位（`action`、`refId`、`hookId`、`url`，以及啟用 Webhook Security 時的 `timeStamp`）與 `subAction`。以下範例為 **Instagram** 的結構：`media_id`，若 mention 位於留言中則另有 `comment_id`。**Facebook** mention 是以 Meta 原生的 Page `mention` change 形式送達，欄位與 Instagram 範例不同；請參閱 Meta 的 Webhook 參考文件以取得 Facebook 的欄位組合。
### 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 動作
當你已連結的內容上有留言被建立時的通知。支援 Facebook 與 Instagram。
Ayrshare 會將 Meta 原生的 comment payload 原樣轉發，僅額外加上標準的封包欄位（`action`、`refId`、`hookId`、`url`，以及啟用 Webhook Security 時的 `timeStamp`）與 `subAction`。以下範例為 **Instagram** 的結構。**Facebook** 留言是以 Page `feed` change 送達，欄位名稱不同（例如 `comment_id`、`post_id`、`message` 與 `from.name`）；請參閱 Meta 的 Webhook 參考文件以取得 Facebook 的欄位組合。
### 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 動作
當某個 automation 為使用者觸發 Webhook 動作時（例如留言或 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
}
```