n8n - Ayrshare API Documentation

n8n là nơi bạn kết nối các công cụ của mình lại với nhau. Ayrshare là một API duy nhất xuất bản đến Facebook, Instagram, LinkedIn, YouTube, TikTok, Pinterest, Reddit, Threads, Bluesky, Telegram, Google Business Profile, Snapchat và X trong một lần gọi. Kết nối chúng với Ayrshare MCP Server và AI Agent n8n của bạn có thể chạy toàn bộ chu trình một mình: soạn thảo bài đăng, xác thực theo quy tắc của từng mạng, xuất bản hoặc lên lịch, sau đó đọc lại phân tích.

The n8n starter workflow on the canvas: a chat trigger into an AI Agent, with an Anthropic chat model and the Ayrshare MCP tool node attached below, plus setup and usage sticky notes.

Vì MCP Server là một endpoint Streamable HTTP được lưu trữ, bạn kết nối nó với node MCP Client Tool tích hợp sẵn của n8n. Không có gì để lưu trữ, không có mã tùy chỉnh và không cần cài đặt community node. Bạn trỏ một node đến một URL và agent của bạn nhận được tất cả 27 công cụ mạng xã hội.

Tải xuống workflow khởi đầu của n8n

Workflow được hiển thị ở trên, sẵn sàng để nhập: Chat Trigger, AI Agent, một model chat Anthropic và node Ayrshare MCP được nối sẵn với system prompt validate-first.

Để sử dụng: trong n8n, Workflows → Import from file, chọn file JSON, sau đó tạo hai credentials mà nó yêu cầu (một credential Bearer Auth giữ khóa Ayrshare của bạn và một credential Anthropic API). Hai huy hiệu cảnh báo sẽ biến mất khi credentials được đính kèm. Các phiên bản tự lưu trữ cần quyền truy cập đi ra tới api.ayrshare.com và nhà cung cấp model của bạn. Hướng dẫn này bao quát toàn bộ đường dẫn MCP-first. Nếu bạn muốn xây dựng một workflow cố định, không dùng agent, có một dự phòng REST ngắn ở cuối.

Tại sao dùng MCP thay vì viết các lệnh gọi API

Bạn có thể gọi REST API của Ayrshare trực tiếp từ node HTTP Request, điều đó ổn cho các workflow cố định, có thể dự đoán được. MCP Server phát huy giá trị khi có LLM tham gia:

Agent chọn công cụ. Mô tả mục tiêu (“xuất bản cái này lên các kênh doanh nghiệp của chúng ta và lên lịch tiếp theo cho thứ Ba”) và agent tự chọn validate_post, create_post, và các tham số đúng.
Xác thực trước khi có gì đó được xuất bản. validate_post dry-run nội dung của bạn theo quy tắc độ dài, định dạng và media của từng nền tảng, để agent không đăng một bài đăng mà mạng sẽ từ chối.
Một lệnh gọi, nhiều mạng. Một create_post duy nhất tỏa ra mọi nền tảng đã liên kết.
Thay đổi nền tảng là vấn đề của Ayrshare. Khi một mạng thay đổi API, Ayrshare duy trì tích hợp và workflow của bạn vẫn hoạt động.
Cùng quy tắc như REST API. Mọi lệnh gọi công cụ MCP chạy trong tiến trình qua cùng chuỗi Ayrshare API: cùng xác thực, giới hạn tốc độ, hạn mức và xác thực. Không có hành vi riêng biệt nào để học.

Cách kết nối

Node AI Agent là bộ não. Sub-node MCP Client Tool gắn vào nó, kết nối tới Ayrshare MCP Server tại https://api.ayrshare.com/mcp, khám phá các công cụ có sẵn và cung cấp chúng cho agent. Khi agent hoạt động, node điều phối lệnh gọi đến Ayrshare, sau đó xuất bản đến các mạng.

Trigger  ->  AI Agent (+ Chat Model)  ->  MCP Client Tool  ->  Ayrshare MCP Server  ->  13 networks

Để biết chi tiết endpoint, transport và xác thực, xem Kết nối & Thiết lập. Để biết danh sách công cụ đầy đủ, xem Danh mục Công cụ.

Điều kiện tiên quyết

Một phiên bản n8n (Cloud hoặc tự lưu trữ) trên phiên bản gần đây với các node AI Agent và MCP Client Tool. Node MCP Client Tool được tích hợp sẵn. Bạn không cần community node, vì server Ayrshare nói Streamable HTTP.
Một tài khoản Ayrshare và API key (Dashboard → Settings → API Key), hoặc bắt đầu dùng thử miễn phí.
Ít nhất một tài khoản xã hội đã liên kết trong Ayrshare. Agent chỉ có thể xuất bản nơi bạn đã kết nối.
Một credential model chat cho node AI Agent (Anthropic, OpenAI, v.v.).
(Tùy chọn) Một Business Plan hoặc Enterprise Plan nếu bạn sẽ quản lý nhiều khách hàng qua các sub-profile.

Thiết lập node MCP Client Tool

Thêm một node AI Agent

Mở hoặc tạo một workflow và thêm một node AI Agent (dưới các node Advanced AI).

Đính kèm node MCP Client Tool

Trên node AI Agent, nhấp vào connector Tool và thêm một node MCP Client Tool. Cấu hình nó:

Trường	Giá trị
Endpoint	`https://api.ayrshare.com/mcp`
Server Transport	`HTTP Streamable`
Authentication	`Bearer Auth`
Tools to Include	`All` (hoặc `Selected` để chỉ cung cấp các công cụ cụ thể)

Thêm khóa Ayrshare của bạn dưới dạng credential Bearer

Đối với Credential, tạo một credential Bearer Auth mới và dán Ayrshare API key của bạn làm token. n8n gửi nó dưới dạng Authorization: Bearer YOUR_API_KEY. Khi bạn lưu, n8n kết nối và liệt kê 27 công cụ.

Kết nối model chat và system prompt

Đính kèm một sub-node Chat Model và chọn credential model của bạn. Cho agent một system prompt đặt ra các quy tắc, ví dụ:

Bạn là trợ lý mạng xã hội có quyền truy cập vào các công cụ Ayrshare. Trước khi xuất bản bất cứ điều gì, luôn gọi validate_post trước và báo cáo bất kỳ vấn đề nào. Chỉ gọi create_post sau khi xác thực thành công. Mặc định là các nền tảng người dùng chỉ định; nếu không có, hãy hỏi. Không bao giờ bịa ra URL media; chỉ sử dụng URL người dùng cung cấp và xác nhận chúng với validate_media khi có nghi ngờ.

Thêm một trigger

Để kiểm thử, Manual Trigger hoặc Chat Trigger là dễ nhất. Đối với sản xuất, sử dụng bất kỳ cái gì kích hoạt workflow (lịch trình, webhook, form, hàng mới trong một sheet).

Sử dụng HTTP Streamable, không phải SSE. Ayrshare MCP Server sử dụng transport Streamable HTTP hiện đại và là stateless. Tùy chọn SSE của n8n đã lỗi thời và server từ chối luồng SSE. Luôn chọn HTTP Streamable.

Bề mặt công cụ

Agent của bạn thấy tất cả 27 công cụ qua một node MCP. Bạn hiếm khi gọi chúng theo tên; bạn mô tả ý định và agent chọn. Các miền là Posts, History, Analytics, Comments, Messages, Profiles, Media, Generate, Webhooks và Errors. Để có danh sách đầy đủ với mục đích và phạm vi của mỗi công cụ, xem Danh mục Công cụ. Hai công cụ nổi bật vì an toàn: validate_post dry-run một bài đăng với cùng đầu vào như create_post nhưng không xuất bản gì, và explain_error chuyển mã lỗi Ayrshare bất kỳ thành nguyên nhân và cách sửa bằng tiếng Anh dễ hiểu, để agent có thể tự chẩn đoán.

Ví dụ 1: soạn thảo, xác thực và xuất bản từ tin nhắn chat

“Hello world” của tích hợp này. Kích hoạt workflow với tin nhắn chat hoặc form và để agent làm phần còn lại.

Trigger: Chat Trigger (hoặc Form Trigger với trường “chúng ta nên đăng gì?”).
Prompt cho agent: “Viết một thông báo ra mắt thân thiện cho bảng điều khiển phân tích mới của chúng ta và xuất bản lên LinkedIn, Facebook và Instagram. Xác thực trước.”

Những gì agent tự làm: nó gọi validate_post với bản sao của bạn và ba nền tảng; nếu Instagram gắn cờ thiếu hình ảnh, nó cho bạn biết thay vì thất bại âm thầm; sau khi xác thực thành công, nó gọi create_post và trả về các URL bài đăng trực tiếp. Vì xác thực chạy trước, bạn tìm ra vấn đề trước khi có gì đó công khai.

Ví dụ 2: tự động xuất bản nội dung mới trên các kênh của bạn

Biến một nguồn nội dung thành các bài đăng đa mạng mà không chạm vào nó.

Trigger: node RSS Read trên feed blog của bạn, một webhook từ CMS của bạn, hoặc một hàng mới trong Google Sheets hoặc Airtable.
Bước AI Agent: “Tóm tắt bài viết này thành một bài đăng xã hội ngắn với 2 đến 3 hashtag liên quan, sau đó xác thực và xuất bản lên LinkedIn, Facebook và Threads.”
Tùy chọn thêm một con người trong vòng lặp phê duyệt trước bước create_post để một người ký duyệt.

Bạn có thể dựa vào recommend_hashtags để có các thẻ dựa trên dữ liệu và generate_post nếu bạn muốn Ayrshare soạn thảo bản sao thay vì model chat của bạn.

Ví dụ 3: bản tin phân tích hàng tuần

Chạy vòng lặp theo hướng ngược lại: đọc hiệu suất và báo cáo nó.

Trigger: node Schedule, ví dụ mỗi thứ Hai lúc 8 giờ sáng.
Bước AI Agent: “Kéo phân tích tài khoản tuần trước cho LinkedIn, Instagram và Facebook, và tóm tắt 3 bài đăng hàng đầu theo mức độ tương tác.”
Agent sử dụng get_social_network_analytics cho các số liệu cấp tài khoản và get_post_analytics cho các bài đăng riêng lẻ, sau đó bạn chuyển tóm tắt của nó đến một node Slack, Gmail, hoặc Notion.

Một lưu ý về nhịp độ: hầu hết các bài đăng nhận được phần lớn tương tác trong 24 giờ đầu tiên và các số liệu không cập nhật theo giây. Lịch trình hàng ngày hoặc hàng tuần là quá đủ. Đừng thăm dò phân tích mỗi vài phút, hoặc bạn sẽ chạm giới hạn tốc độ mà không có dữ liệu mới.

Hành động thay mặt cho khách hàng (đa người thuê)

Nếu bạn quản lý mạng xã hội cho nhiều khách hàng, profiles của Ayrshare cho phép một tài khoản đăng lên nhiều bộ tài khoản đã liên kết khác nhau. Trên Business Plan hoặc Enterprise Plan, bạn có hai cách để nhắm mục tiêu một khách hàng từ n8n:

Theo kết nối: thêm một header Profile-Key vào node MCP Client Tool (sử dụng xác thực Multiple Headers để bạn có thể gửi cả Authorization và Profile-Key). Mỗi lệnh gọi trên node đó sau đó hoạt động như khách hàng đó. Tốt khi một workflow phục vụ một khách hàng.
Theo lệnh gọi: nhiều công cụ chấp nhận một đối số profileKey, mà agent có thể đặt theo hành động. Khi cả hai đều có, đối số theo lệnh gọi thắng. Tốt khi một workflow định tuyến qua các khách hàng.

Để đưa một khách hàng mới vào hệ thống, agent có thể gọi create_profile và sau đó generate_jwt_social_linking_url để tạo một trang được lưu trữ nơi khách hàng liên kết các tài khoản của chính họ. Không có thông tin xác thực nào đi qua workflow của bạn.

Đăng lên X/Twitter

Trong n8n, chuyển Authentication của node MCP Client Tool sang Multiple Headers và thêm hai header X-Twitter-OAuth1-* cùng với Authorization. Đây là thiết lập một lần cho mỗi tài khoản Ayrshare và cùng cặp khóa áp dụng cho mọi profile. Đối với mọi thứ khác (Facebook, Instagram, LinkedIn, YouTube, TikTok, và phần còn lại) không cần header bổ sung. Xem Kết nối & Thiết lập → Thông tin xác thực BYO cho X/Twitter.

Giữ con người trong vòng lặp

Các công cụ MCP làm cho việc agent xuất bản trở nên đơn giản, đó chính là lý do bạn nên kiểm soát. Hai biện pháp bảo vệ rẻ tiền:

Luôn xác thực trước. Đưa “gọi validate_post trước create_post” vào system prompt. Xác thực không xuất bản gì và bắt các vi phạm quy tắc nền tảng sớm.
Thêm một bước phê duyệt. Chèn node Send and Wait for Response của n8n (Slack hoặc email) giữa bản nháp và hành động xuất bản để một người phê duyệt trước khi có gì đó đi vào hoạt động. Đối với nội dung đã lên lịch, agent có thể sử dụng update_post để sửa đổi một bài đăng đang chờ phê duyệt.

Dự phòng REST (không có agent)

Nếu bạn muốn một workflow cố định, xác định mà không có LLM, hãy bỏ qua MCP và gọi REST API với một node HTTP Request:

Method: POST
URL: https://api.ayrshare.com/api/post
Authentication: Header Auth, Authorization: Bearer YOUR_API_KEY

{
  "post": "Excited to announce our new feature!",
  "platforms": ["facebook", "linkedin", "instagram"],
  "mediaUrls": ["https://example.com/image.jpg"],
  "scheduleDate": "2026-07-01T10:00:00Z"
}

Sử dụng máy chủ API api.ayrshare.com, không phải máy chủ dashboard app.ayrshare.com. (app.ayrshare.com sẽ chấp nhận các lệnh gọi API, nhưng nó không phải là endpoint được tài liệu hóa và có thể trả về lỗi 502/504 gateway không liên tục, vì vậy luôn sử dụng api.ayrshare.com.) Mẫu tương tự hoạt động cho các endpoint REST khác. Đây là công cụ phù hợp khi workflow hoàn toàn có thể dự đoán được và bạn không cần một agent quyết định bất cứ điều gì.

Xử lý sự cố

Triệu chứng	Nguyên nhân có thể	Cách khắc phục
Lệnh gọi công cụ trả về `403` / code `102`, “API Key not valid”	Sai hoặc thiếu API key	Kiểm tra credential Bearer Auth giữ khóa Ayrshare chính xác của bạn. Lưu lại node sau khi thay đổi.
n8n không thể kết nối tới MCP server	Sai transport hoặc endpoint	Endpoint phải là `https://api.ayrshare.com/mcp`; transport phải là HTTP Streamable, không phải SSE.
Bài đăng X/Twitter thất bại với lỗi `419`	Thiếu thông tin xác thực BYO cho X	Thêm hai header `X-Twitter-OAuth1-*` qua xác thực Multiple Headers.
Bài đăng thất bại chỉ cho một nền tảng	Mạng đó chưa được liên kết, hoặc thiếu trường bắt buộc	Liên kết nó trong bảng điều khiển; thêm `title` cho YouTube, `title` + `subreddit` cho Reddit, `mediaUrls` cho Instagram.
Bài đăng Instagram bị từ chối	Không có media	Instagram yêu cầu `mediaUrls` cho hầu hết các loại bài đăng. Hãy để agent xác nhận với `validate_media`.
Media được đính kèm dưới dạng file hoặc binary không xuất hiện	MCP chỉ là JSON	Tham chiếu media theo URL `mediaUrls` công khai; đường dẫn MCP không chấp nhận tải lên tệp. Xác nhận URL với `validate_media`.
Các lệnh gọi hoạt động, nhưng tác động lên nhầm khách hàng	Nhắm mục tiêu profile	Đặt một header `Profile-Key` (theo kết nối) hoặc đối số `profileKey` (theo lệnh gọi); đối số thắng nếu cả hai đều được đặt.
`429 Too Many Requests`	Thăm dò quá thường xuyên	Giảm tần suất thăm dò phân tích và bình luận; số liệu không cập nhật theo giây.
Thay đổi cấu hình không có hiệu lực	Kết nối MCP khởi tạo khi bắt đầu phiên	Lưu lại node hoặc khởi động lại workflow sau khi thay đổi khóa hoặc các header.

Bạn cũng có thể cung cấp công cụ explain_error cho agent để nó tự giải mã bất kỳ mã lỗi Ayrshare nào thành nguyên nhân và cách khắc phục.

Các bước tiếp theo

Kết nối & Thiết lập

Endpoint, transport, xác thực, nhắm mục tiêu profile và thông tin xác thực BYO.

Danh mục Công cụ

27 công cụ được nhóm theo miền, với phạm vi và mục đích.

MCP Server

MCP Server là gì và cách nó ánh xạ tới Ayrshare API.

Plugin Claude Code

Cùng server, đóng gói cho Claude Code.

Tải xuống workflow khởi đầu của n8n

​Tại sao dùng MCP thay vì viết các lệnh gọi API

​Cách kết nối

​Điều kiện tiên quyết

​Thiết lập node MCP Client Tool

​Bề mặt công cụ

​Ví dụ 1: soạn thảo, xác thực và xuất bản từ tin nhắn chat

​Ví dụ 2: tự động xuất bản nội dung mới trên các kênh của bạn

​Ví dụ 3: bản tin phân tích hàng tuần

​Hành động thay mặt cho khách hàng (đa người thuê)

​Đăng lên X/Twitter

​Giữ con người trong vòng lặp

​Dự phòng REST (không có agent)

​Xử lý sự cố

​Các bước tiếp theo

Kết nối & Thiết lập

Danh mục Công cụ

MCP Server

Plugin Claude Code

Tại sao dùng MCP thay vì viết các lệnh gọi API

Cách kết nối

Điều kiện tiên quyết

Thiết lập node MCP Client Tool

Bề mặt công cụ

Ví dụ 1: soạn thảo, xác thực và xuất bản từ tin nhắn chat

Ví dụ 2: tự động xuất bản nội dung mới trên các kênh của bạn

Ví dụ 3: bản tin phân tích hàng tuần

Hành động thay mặt cho khách hàng (đa người thuê)

Đăng lên X/Twitter

Giữ con người trong vòng lặp

Dự phòng REST (không có agent)

Xử lý sự cố

Các bước tiếp theo