Tổng quan về Automations API - Ayrshare API Documentation

Beta. Automations API đang trong giai đoạn beta và chúng tôi đang tích cực thu thập phản hồi. Các endpoint, payload và giới hạn có thể thay đổi khi chúng tôi lặp lại. Vui lòng gửi phản hồi và báo cáo lỗi tới support để chúng tôi có thể ưu tiên các cải tiến phù hợp.

Các endpoint Automations cho phép bạn định nghĩa các quy tắc tự động phản ứng với tương tác Instagram đến. Mỗi automation kết hợp một hoặc nhiều trigger (sự kiện kích hoạt quy tắc) với một hoặc nhiều action (điều gì xảy ra khi kích hoạt). Một quy tắc duy nhất có thể lắng nghe nhiều trigger và điều phối nhiều action — kích hoạt một webhook vào pipeline phân tích của bạn VÀ gửi một DM từ cùng một tương tác. Engine chạy hoàn toàn bên trong khuôn khổ chính sách của Meta (không có DM được kích hoạt khi có follow mới, không có tin nhắn đầu tiên tới người lạ, không có gửi hàng loạt) và kế thừa giới hạn tốc độ theo tài khoản của Ayrshare, deduplication theo người nhận, và ingestion webhook idempotent.

Cách hoạt động

Tạo một automation

POST /automations với các trigger và action mà bạn muốn. Automation được kích hoạt ngay lập tức.

Người dùng cuối tương tác

Ai đó bình luận trên bài đăng của bạn, trả lời story của bạn, gửi DM hoặc phản ứng với một DM. Meta gửi webhook tới Ayrshare.

Ayrshare khớp và điều phối

Engine tra cứu mọi quy tắc khớp với sự kiện, kiểm tra deduplication theo action và giới hạn DM hàng ngày của bạn, sau đó chạy mỗi action. Một khoảng jitter 20–60 giây được áp dụng cho việc gửi DM để giữ an toàn bên trong heuristic chống spam của Instagram.

Kiểm tra những gì đã kích hoạt

GET /automations/:id/activity trả về nhật ký kiểm toán — mọi lần thử điều phối, kết quả của từng action, và bất kỳ lỗi nào.

Trigger

Bạn có thể đính kèm tối đa 50 trigger cho một automation. Mỗi trigger là một discriminated union trên trường type; các trường dành riêng cho type nằm cùng cấp. Tất cả trigger đều chỉ dành cho Instagram trong v1.

Loại	Kích hoạt khi	Cấu hình
`comment_keyword`	Một bình luận khớp với từ khóa xuất hiện trên một bài đăng cụ thể	`postId` (bắt buộc); `keywords` (bắt buộc, ≥1 mục)
`story_reply`	Người dùng trả lời một story qua DM	`storyId` (tùy chọn)
`dm_reaction`	Người dùng phản ứng với một trong các DM của bạn bằng emoji	`emoji` (tùy chọn — bỏ qua để kích hoạt trên bất kỳ emoji nào)
`dm_keyword`	Người dùng gửi một DM có văn bản khớp với từ khóa	`keywords` (bắt buộc, ≥1 mục)

Khớp từ khóa không phân biệt chữ hoa/chữ thường và theo toàn bộ từ. Một sự kiện đáp ứng trigger được lọc theo từ khóa nếu nó chứa bất kỳ một trong các từ khóa đã cấu hình. Bỏ qua storyId trên một story trigger để kích hoạt trên mọi story cho tài khoản đã kết nối.

Action

Bạn có thể đính kèm tối đa 50 action cho một automation. Chúng chạy tuần tự; mỗi kết quả được ghi lại trên hàng activity.

Loại	Hiệu ứng	Cấu hình
`send_dm`	Gửi một DM Instagram tới người dùng đã kích hoạt quy tắc, sử dụng một tin nhắn có template.	`message` (bắt buộc, có template)
`fire_webhook`	POST ngữ cảnh automation tới URL webhook cấp tài khoản của bạn (cấu hình qua `POST /hook/webhook`).	(không có — hình dạng payload cố định; xem bên dưới)
`send_email`	Xếp hàng một email qua pipeline mail của nền tảng.	`to` (bắt buộc, email); `subject` (tùy chọn, có template); `message` (bắt buộc, có template)

Cửa sổ dedup theo action

Mọi action — bất kể loại — cũng chấp nhận một trường dedupWindowMinutes cấp cao nhất tùy chọn ghi đè cửa sổ dedup mặc định 7 ngày theo người nhận chỉ cho action đó.

Đặt thành 0 để vô hiệu hóa dedup hoàn toàn cho action đó (điển hình cho fire_webhook / send_email nơi người nhận mong đợi mọi sự kiện).
Giới hạn tối đa ở 525600 (một năm).

Action with a 24h dedup override

{
  "type": "send_dm",
  "message": "Thanks {{recipient_username}}!",
  "dedupWindowMinutes": 1440
}

Payload `fire_webhook`

Khi fire_webhook chạy, nó POST một body JSON tới URL webhook cấp tài khoản của bạn:

{
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "jane_doe",
  "keyword":           "LINK",
  "timestamp":         "2026-05-12T09:14:22.000Z"
}

recipientUsername và keyword là null khi trigger không điền chúng (ví dụ: dm_keyword không mang username trên payload của Meta; story_reply không có từ khóa).

Biến template

send_dm.message, send_email.subject, và send_email.message hỗ trợ thay thế {{placeholder}}. Các placeholder không xác định bị từ chối tại thời điểm tạo/cập nhật (dưới dạng lỗi validation 473) để một lỗi đánh máy không bao giờ ngầm rò rỉ chuỗi ký tự {{foo}} vào một tin nhắn hướng tới khách hàng.

Placeholder	Phân giải thành
`{{recipient_username}}`	Handle Instagram của người dùng đang tương tác (khi webhook mang nó)
`{{recipient_id}}`	ID người tham gia Instagram của người dùng đang tương tác (IGSID)
`{{recipient_name}}`	Dành riêng; phân giải thành rỗng cho đến khi một nguồn enrichment tương lai điền nó
`{{sender_username}}`	Tên người dùng Instagram đã liên kết của bạn
`{{sender_name}}`	Tên hiển thị Instagram đã liên kết của bạn
`{{comment_text}}`	Văn bản của bình luận / DM / story reply đã kích hoạt trigger
`{{comment_id}}`	ID nền tảng của bình luận / tin nhắn đã kích hoạt
`{{comment_sent_at}}`	Timestamp ISO 8601 của sự kiện (khi khả dụng)
`{{matched_keyword}}`	Từ khóa đã khớp (hoặc chuỗi emoji cho `dm_reaction`)
`{{platform}}`	Định danh nền tảng (ví dụ: `instagram`)
`{{trigger_type}}`	Loại trigger (ví dụ: `comment_keyword`)

Không có sender_email / recipient_email. Các placeholder này cố ý không được hiển thị — email thanh toán của bạn không có chỗ hợp pháp trong một DM tới người lạ, và Meta không cung cấp email của người nhận trên bất kỳ webhook IG nào. Việc tránh các placeholder ngăn ngừa việc tiết lộ ngẫu nhiên.

Ví dụ template:

Hey {{recipient_username}}, thanks for the comment "{{comment_text}}" — here is the link you wanted: https://example.com

Giới hạn tốc độ và giới hạn

Gói	Automation đang hoạt động (mỗi profile)	Giới hạn DM hàng ngày (mỗi tài khoản)
Business	10	1.000
Enterprise	50	5.000

Giới hạn automation-đang-hoạt-động được tính theo User Profile, không phải theo tài khoản cha. Mỗi profile dưới tài khoản của bạn nhận được Business 10 / Enterprise 50 riêng, do đó một tài khoản có nhiều profile có thể chạy chừng đó automation trên mỗi profile. Nó tính các automation đang hoạt động và được thực thi trên cả POST (tạo) và kích hoạt lại PUT (active: false → true), mỗi lần đều hiển thị mã lỗi 470. Cần giới hạn cao hơn theo profile? Liên hệ hỗ trợ để tăng nó cho tài khoản của bạn. Giới hạn DM hàng ngày áp dụng cho mỗi tài khoản Ayrshare cha, được chia sẻ trên tất cả profile của bạn, với một giới hạn phụ theo profile để một profile bận rộn không thể làm cạn hạn mức của toàn bộ tài khoản. Khi đạt đến giới hạn DM, hàng activity ghi lại trạng thái rate_limited và không có DM nào được gửi. Giới hạn cấu trúc trên một automation: 1–50 trigger, 1–50 action. Chính Instagram giới hạn DM ở khoảng 200/giờ mỗi tài khoản. Engine điều chỉnh việc điều phối với một jitter 20–60 giây để giữ an toàn dưới mức này.

Trạng thái Activity

Một hàng trong GET /automations/:id/activity mang một status cấp cao nhất cộng với một status theo action bên trong actionResults[]:

Trạng thái	Ý nghĩa
`pending`	Vừa mới được ghi; worker chưa nhận nó
`in_flight`	Worker hiện đang điều phối
`sent`	Mọi action đã thành công
`failed`	Ít nhất một action thất bại (và không có action nào gặp lỗi xác thực)
`auth_error`	Access token Instagram không hợp lệ; DM không được thử lại
`rate_limited`	Đã đạt đến giới hạn DM hàng ngày (theo gói hoặc theo profile); không có DM nào được gửi
`deduplicated`	Action này đã kích hoạt tới người nhận này trong cửa sổ dedup của nó
`skipped`	Automation trở nên không hoạt động hoặc đã bị xóa giữa fan-out và điều phối

pending và in_flight là tạm thời; mọi trạng thái khác là cuối cùng.

Mã lỗi

API trả về hai dạng lỗi:

Lỗi quy tắc kinh doanh mang một code automation được đánh số (ví dụ: { "action": "automation", "code": 469, ... }).
Lỗi validation — bất kỳ body yêu cầu bị lỗi định dạng nào (trường thiếu hoặc không hợp lệ, biến template không xác định, khóa không được nhận dạng) — được trả về dưới dạng một phản hồi 473 duy nhất với đối tượng details liệt kê các trường vi phạm. details là kết quả của validator (formErrors cộng với fieldErrors). Phân nhánh trên details, không phải trên mã theo điều kiện. Trong fieldErrors, các khóa là các trường yêu cầu cấp cao nhất (triggers, actions): một vấn đề bên trong một mục cụ thể, chẳng hạn như một trigger thiếu keywords, được báo cáo dưới trường đó (ví dụ: triggers), trong khi formErrors giữ các vấn đề cấp đối tượng như các khóa không được nhận dạng.

Mã	HTTP	Ý nghĩa
468	403	Yêu cầu gói Business hoặc Enterprise
469	404	Không tìm thấy automation (cũng được trả về khi người gọi không sở hữu nó)
470	429	Đã đạt đến giới hạn automation đang hoạt động cho cấp gói của bạn
471	400	Không có tài khoản mạng xã hội nào được liên kết trên nền tảng được yêu cầu cho profile này
472	403	Tính năng chưa khả dụng trên tài khoản của bạn — liên hệ với chúng tôi để truy cập sớm
473	400	Validation thất bại (body yêu cầu bị lỗi định dạng) — kiểm tra `details`

Những gì Meta KHÔNG cho phép

Một số khả năng thường được yêu cầu không được hỗ trợ vì Meta không cho phép chúng trên Instagram API công khai:

Tự động DM cho người theo dõi mới. Instagram không xuất bản một webhook follow.
DM tin nhắn đầu tiên cho người lạ. Meta yêu cầu người nhận khởi tạo liên hệ (bình luận, trả lời, DM, phản ứng) trước khi một tài khoản doanh nghiệp có thể nhắn tin cho họ — đó chính xác là những gì mọi trigger được hỗ trợ ở đây đại diện.
Chiến dịch gửi hàng loạt. Giới hạn DM theo giờ và heuristic chống lạm dụng áp dụng ở cấp nền tảng.

Sử dụng đa profile

Các endpoint tôn trọng header profileKey. Truyền khóa của một profile con và automation được tạo/quản lý dưới profile đó. Giới hạn tốc độ được chia trên các profile thông qua một giới hạn phụ theo profile để một profile hoạt động sôi nổi không làm cạn hạn mức của tài khoản cha.

Câu hỏi thường gặp

Tôi có thể kích hoạt trên một người theo dõi mới không?

Không. Instagram không xuất bản một webhook follow, và Meta không cho phép các ứng dụng bên thứ ba gửi DM tới người dùng chưa khởi tạo cuộc trò chuyện. Mọi trigger được hỗ trợ (comment_keyword, story_reply, dm_reaction, dm_keyword) đều đáp ứng yêu cầu “người dùng liên hệ với bạn trước”.

Điều gì xảy ra nếu access token của tôi không hợp lệ khi một automation kích hoạt?

Hàng activity ghi lại trạng thái auth_error và DM không được thử lại. Liên kết lại tài khoản, sau đó tương tác khớp tiếp theo sẽ kích hoạt bình thường.

Tại sao có độ trễ trước khi DM được gửi?

Mỗi lần điều phối send_dm được lên lịch 20–60 giây sau khi có tương tác để trông tự nhiên đối với hệ thống chống spam của Instagram. Các action fire_webhook và send_email KHÔNG có jitter. Timestamp created của hàng activity là khi trigger khớp; completedAt là khi việc điều phối hoàn thành.

Các hàng activity có được giữ mãi không?

Các hàng activity được giữ vô thời hạn để theo dõi và phân tích. Endpoint GET /automations/:id/activity trả về các hàng từ 30 ngày qua để đảm bảo hiệu suất. (Bảo vệ dedup sử dụng cửa sổ theo action riêng của nó — mặc định là 7 ngày — không liên quan đến khoảng thời gian activity lookback.)

Xóa một automation có xóa lịch sử activity của nó không?

Không. Xóa là soft-delete: hàng master được đánh dấu deleted, không có điều phối mới nào xảy ra, nhưng các hàng activity lịch sử vẫn có thể đọc được qua endpoint activity.

Endpoint

POST /automations — tạo một automation mới
GET /automations — liệt kê các automation của bạn
GET /automations/:id — lấy một automation với các trigger và action của nó
PUT /automations/:id — cập nhật một phần; tạm dừng qua active: false
DELETE /automations/:id — soft-delete
GET /automations/:id/activity — nhật ký kiểm toán điều phối được phân trang theo cursor

​Cách hoạt động

​Trigger

​Action

​Cửa sổ dedup theo action

​Payload fire_webhook

​Biến template

​Giới hạn tốc độ và giới hạn

​Trạng thái Activity

​Mã lỗi

​Những gì Meta KHÔNG cho phép

​Sử dụng đa profile

​Câu hỏi thường gặp

​Endpoint

Cách hoạt động

Trigger

Action

Cửa sổ dedup theo action

Payload `fire_webhook`

Biến template

Giới hạn tốc độ và giới hạn

Trạng thái Activity

Mã lỗi

Những gì Meta KHÔNG cho phép

Sử dụng đa profile

Câu hỏi thường gặp

Endpoint