Webhook Actions - Ayrshare API Documentation

Có nhiều loại webhook có sẵn và được phân loại theo loại Action. Ví dụ, một bài đăng đã lên lịch sẽ kích hoạt webhook action scheduled. Vui lòng xem tổng quan webhook để biết thêm chi tiết. Sau khi đăng ký một URL webhook, bạn sẽ nhận được yêu cầu POST đến URL của mình khi một sự kiện xảy ra. Yêu cầu POST sẽ bao gồm một payload JSON với chi tiết sự kiện.

Scheduled Action

Bạn sẽ nhận được thông báo webhook này khi một bài đăng đã lên lịch được xử lý — dù thành công hay thất bại — và được đăng lên các mạng xã hội đã chọn. Ví dụ, nếu bạn lên lịch một bài đăng cho 12:00 PM ngày 1 tháng 8 năm 2026, webhook sẽ được gửi vào chính thời điểm bài đăng được xuất bản. Thông báo webhook chỉ được gửi cho các bài đăng được lên lịch trong tương lai bằng trường scheduleDate trong endpoint /post.

Scheduled Event

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

Bạn sẽ không nhận được thông báo webhook cho các bài đăng ngay lập tức, vì API trả về phản hồi thành công hoặc thất bại ngay lập tức trong phản hồi JSON. Thông báo webhook chỉ được gửi cho các bài đăng đã lên lịch, vì những bài này được xử lý bất đồng bộ và yêu cầu thông báo riêng để thông báo cho bạn về trạng thái của chúng.

TikTok Publishing Webhook

Khi làm việc với TikTok qua Ayrshare, bạn có thể nhận được hai webhook khác nhau cho một bài đăng đã lên lịch. Nếu bài đăng của bạn được lên lịch thay vì đăng ngay lập tức, bạn sẽ nhận được webhook Scheduled Action tiêu chuẩn trước. Điều này cho biết phương tiện đã được gửi thành công đến TikTok để xử lý và đăng. Sau đó, bạn sẽ nhận được webhook subAction: tikTokPublished. Điều này được kích hoạt sau khi TikTok đã hoàn thành xử lý phương tiện và phương tiện được công khai. Webhook này được kích hoạt cho cả bài đăng ngay lập tức và bài đăng đã lên lịch. Trong bảng điều khiển Ayrshare, sự kiện này được gắn nhãn là tikTok (pub).

Webhook tikTokPublished không được gửi cho đến khi phương tiện được công khai. Nếu phương tiện được đặt thành riêng tư, người theo dõi, hoặc bạn bè, webhook sẽ không được gửi.Nếu bạn không nhận được webhook tikTokPublished và trạng thái bài đăng vẫn là pending, hãy kiểm tra ứng dụng di động TikTok để đảm bảo phương tiện đã được TikTok chấp nhận.

Thông báo khi profile của người dùng liên kết hoặc hủy liên kết một mạng xã hội.

{
  "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 là system có nghĩa là Ayrshare tự động hủy liên kết tài khoản, chẳng hạn như khi kết nối mạng xã hội không còn hợp lệ. Chúng tôi khuyến nghị bạn thông báo cho người dùng của mình để họ có thể tiếp tục đăng bài. Chi tiết về việc hủy liên kết được tìm thấy trong trường details. Một email cũng sẽ được gửi đến địa chỉ email của Primary Account, hoặc email thay thế nếu chúng đã được thiết lập. source là user có nghĩa là người dùng đã tự khởi động hành động, chẳng hạn như họ hủy liên kết tài khoản theo cách thủ công. Email sẽ không được gửi khi xảy ra hành động do người dùng khởi tạo.

Messages Action

Yêu cầu Messaging Add-On để truy cập tất cả các endpoint và webhook messages. Thông báo khi một tin nhắn trực tiếp mới đến, được đọc bởi người dùng, hoặc một reaction được tạo hoặc xóa trên tin nhắn chỉ dành cho Facebook và Instagram. Webhook X/Twitter có sẵn dưới dạng tùy chọn cho khách hàng Enterprise. Vui lòng liên hệ với đại diện tài khoản của bạn để biết thêm thông tin về việc trở thành khách hàng Enterprise.

Phạm vi Standby cho Facebook Pages với nhiều ứng dụng

Ayrshare đăng ký trường webhook standby của Facebook ngoài các trường messaging tiêu chuẩn. Điều này có nghĩa là các sự kiện Messenger được gửi đến webhook của bạn ngay cả khi ứng dụng khác trên cùng Facebook Page hiện đang giữ quyền điều khiển thread — ví dụ, khi nền tảng chatbot được đặt làm primary receiver của Page, hoặc khi Meta’s Page Inbox đang xử lý cuộc trò chuyện. Không có thay đổi lược đồ cho các sự kiện này. Chúng đến dưới dạng cùng các payload messageCreated / messageRead / reactionCreated / messageEdited được ghi lại trong các phần bên dưới. Hai điều cần lưu ý cho Pages có ứng dụng Messenger cạnh tranh được cài đặt:

Khối lượng tin nhắn đến có thể tăng so với hành vi trước đây, khi các sự kiện standby được bỏ qua âm thầm trước khi được đăng ký. Lưu lượng mới thể hiện các tin nhắn mà Page của bạn đã nhận được đang được xử lý bởi ứng dụng khác.
Bạn có thể nhận được sự kiện messageCreated với type: "sent" không tương ứng với các tin nhắn bạn đã gửi qua Ayrshare. Đây là echo của các tin nhắn được gửi bởi ứng dụng Messenger khác trên Page của bạn (Meta gửi một bản sao của mỗi lần gửi đến mỗi ứng dụng đã đăng ký). Nếu tích hợp của bạn đối chiếu lưu lượng đi với lịch sử gửi riêng của mình, bạn có thể sử dụng lịch sử đó để phân biệt các lần gửi của mình với các lần gửi của ứng dụng cạnh tranh.

Đối với Pages chỉ cài đặt Ayrshare (không có ứng dụng Messenger cạnh tranh), thay đổi có thể quan sát được duy nhất là Message Edit Event mới — mọi thứ khác trông giống như hành vi trước đây.

New Message Events

Thông báo khi một tin nhắn mới được gửi hoặc nhận.

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

Message Read Event

Thông báo khi một tin nhắn được đọc bởi người nhận.

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

Khi một tin nhắn được đọc trên Instagram, payload webhook bao gồm trường mid xác định duy nhất tin nhắn cụ thể nào đã được đọc. Đối với tin nhắn Facebook, việc đọc tin nhắn được theo dõi ở cấp cuộc trò chuyện bằng cách sử dụng conversationId. Khi sự kiện đọc xảy ra, tất cả các tin nhắn trong cuộc trò chuyện đó với dấu thời gian trước dấu thời gian created (hoặc read) nên được coi là đã được đọc bởi người dùng.

Reaction Created and Deleted Events

Thông báo khi một reaction, chẳng hạn như like, được tạo hoặc xóa trên một tin nhắn.

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

Message Edit Event

Thông báo khi người dùng chỉnh sửa một tin nhắn họ đã gửi trước đó. Có sẵn cho tin nhắn trực tiếp Facebook và Instagram. Trường messageEdit.mid khớp với id của sự kiện messageCreated gốc, để người tiêu dùng có thể tương quan chỉnh sửa với tin nhắn gốc. Trường messageEdit.text mang văn bản tin nhắn mới đã chỉnh sửa.

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

Thông báo khi một batch đã hoàn thành xử lý và tệp có sẵn, chẳng hạn như lấy tất cả user profile. Bạn có thể truy cập tệp bằng URL pre-signed trong trường url.

Batch Event

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

Thông báo khi một mục RSS feed mới được tìm thấy cho các RSS feed đã đăng ký. Lưu ý: nếu Webhook đang hoạt động, các mục RSS mới sẽ không được tự động đăng lên các mạng xã hội.

Feed Event

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

Thông báo khi tài khoản đã kết nối của bạn được nhắc đến. Có sẵn cho Facebook và Instagram. Ayrshare chuyển tiếp payload mention gốc của Meta không thay đổi, chỉ thêm các trường envelope tiêu chuẩn (action, refId, hookId, url, và timeStamp với Webhook Security) và subAction. Ví dụ dưới đây có hình dạng Instagram: media_id, cộng với comment_id khi mention nằm trong một bình luận. Các mention Facebook đến dưới dạng thay đổi mention Page gốc của Meta, có các trường khác với ví dụ Instagram; hãy tham khảo tài liệu tham khảo webhooks của Meta để biết bộ trường Facebook.

Mention Event (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

Thông báo khi một bình luận được tạo trên nội dung đã kết nối của bạn. Có sẵn cho Facebook và Instagram. Ayrshare chuyển tiếp payload bình luận gốc của Meta không thay đổi, chỉ thêm các trường envelope tiêu chuẩn (action, refId, hookId, url, và timeStamp với Webhook Security) và subAction. Ví dụ dưới đây có hình dạng Instagram. Các bình luận Facebook đến dưới dạng một thay đổi feed Page với tên trường khác (ví dụ comment_id, post_id, message, và from.name); hãy tham khảo tài liệu tham khảo webhooks của Meta để biết bộ trường Facebook.

Comment Event (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

Thông báo khi một automation kích hoạt một hành động webhook cho người dùng, chẳng hạn như trình kích hoạt trả lời tự động comment hoặc DM.

Automation Event

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

​TikTok Publishing Webhook

​Social Action

​Social Action Event

​Messages Action

​Phạm vi Standby cho Facebook Pages với nhiều ứng dụng

​New Message Events

​Message Read Event

​Reaction Created and Deleted Events

​Message Edit Event

​Batch Action

​Batch Event

​Feed Action

​Feed Event

​Mentions Action

​Mention Event (Instagram)

​Comments Action

​Comment Event (Instagram)

​Automations Action

​Automation Event

Scheduled Action

Scheduled Event

TikTok Publishing Webhook

Social Action

Social Action Event

Messages Action

Phạm vi Standby cho Facebook Pages với nhiều ứng dụng

New Message Events

Message Read Event

Reaction Created and Deleted Events

Message Edit Event

Batch Action

Batch Event

Feed Action

Feed Event

Mentions Action

Mention Event (Instagram)

Comments Action

Comment Event (Instagram)

Automations Action

Automation Event