Webhook 動作 - Ayrshare API Documentation

Webhook 有多種類型，並依據動作類型（Action）分類。例如，一則排程貼文會觸發 scheduled 動作的 Webhook。更多細節請參閱 Webhook 概觀。在註冊 Webhook URL 之後，當事件發生時，你會收到一個 POST 請求送到該 URL。該 POST 請求會包含含有事件詳細內容的 JSON payload。

Scheduled 動作

當排程貼文被處理時（無論成功或失敗）並發布至所選的社群網路時，你會收到此 Webhook 通知。例如，若你將貼文排程於 2026 年 8 月 1 日中午 12:00，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 動作 Webhook。這代表媒體已成功送至 TikTok，等待處理與發布。之後，你會收到 subAction: tikTokPublished Webhook。一旦 TikTok 完成媒體的處理且媒體被公開後，即會觸發此 Webhook。此 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 動作

存取所有 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）的粉絲專頁而言，唯一可觀察到的變化是新的訊息編輯事件——其他一切與過去行為相同。

新訊息事件

當有新訊息被送出或收到時的通知。

{
  "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 payload 會包含一個 mid 欄位，用來唯一識別哪一則訊息被已讀。對於 Facebook 訊息，訊息已讀是以對話層級透過 conversationId 進行追蹤。當已讀事件發生時，該對話中時間戳早於 created（或 read）時間戳的所有訊息，都應被視為已被使用者讀取。

反應建立與刪除事件

當訊息上有反應（例如 like）被建立或刪除時的通知。

{
  "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 私訊。 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 動作

當某個批次完成處理且檔案已可存取時的通知，例如取得所有 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 動作

當已註冊的 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 動作

當你已連結的帳號被提及（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）

{
  "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）

{
  "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 事件

{
  "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 動作

​Scheduled 事件

​TikTok 發布 Webhook

​Social 動作

​Social 動作事件

​Messages 動作

​針對安裝了多個 App 的 Facebook 粉絲專頁的 Standby 涵蓋

​新訊息事件

​訊息已讀事件

​反應建立與刪除事件

​訊息編輯事件

​Batch 動作

​Batch 事件

​Feed 動作

​Feed 事件

​Mentions 動作

​Mention 事件（Instagram）

​Comments 動作

​Comment 事件（Instagram）

​Automations 動作

​Automation 事件

Scheduled 動作

Scheduled 事件

TikTok 發布 Webhook

Social 動作

Social 動作事件

Messages 動作

針對安裝了多個 App 的 Facebook 粉絲專頁的 Standby 涵蓋

新訊息事件

訊息已讀事件

反應建立與刪除事件

訊息編輯事件

Batch 動作

Batch 事件

Feed 動作

Feed 事件

Mentions 動作

Mention 事件（Instagram）

Comments 動作

Comment 事件（Instagram）

Automations 動作

Automation 事件