> ## 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 Actions
> Webhook Actions và Events
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](/apis/webhooks/overview) để 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](/apis/post/post).
### Scheduled Event
```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
}
```
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](/apis/post/social-networks/tiktok#visibility-options).
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.
## Social Action
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.
### Social Action Event
```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` 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ế](/multiple-users/manage-user-profiles#alternative-emails-for-alerts) 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](#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.
```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
}
```
### Message Read Event
Thông báo khi một tin nhắn được đọc bởi người nhận.
```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
}
```
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.
```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
}
```
### 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.
```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
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](/apis/user/batch-all-users). Bạn có thể truy cập tệp bằng URL pre-signed trong trường `url`.
### Batch Event
```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
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
```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
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)
```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
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)
```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
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
```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
}
```