Profiles

Một Profile là một thương hiệu, khách hàng hoặc tài khoản con mà bạn đăng bài thay mặt, tức một nhóm tài khoản mạng xã hội đã kết nối. Mỗi bài đăng chỉ gửi qua đúng một Profile. Đây là cùng một đối tượng, dù bạn làm việc theo cách nào:

Trên dashboard: mỗi thương hiệu hiện ra trong mục Kết nối dưới dạng một Profile. Phần lớn khách hàng tạo và kết nối Profile tại đây, không cần code.
Qua API: bạn tham chiếu chính Profile đó bằng profile_id (9f2b4c17-…) trong mỗi lần đăng bài.

Một API key quản lý tất cả Profile của bạn, không cần key riêng cho từng thương hiệu:

API key của bạn
├── Profile: Acme Coffee   → Instagram, Facebook (3 Page), TikTok
├── Profile: Acme Tea      → Instagram, X
└── Profile: Khách hàng — Nova → LinkedIn, YouTube

Một Profile chứa được nhiều Facebook Page, bạn không cần tạo Profile riêng cho từng Page. Sau khi kết nối, dashboard liệt kê đủ các Page của tài khoản Facebook đó và mỗi bài đăng chọn một Page bằng facebook_page_id (tự chọn nếu Profile chỉ có một Page). Muốn đăng cùng nội dung lên nhiều Page thì gửi nhiều bài, mỗi bài một Page. Xem mục Tìm ID của Page & board bên dưới. Có một ngoại lệ: nếu một Page được ghim vào Profile thì ghim thắng facebook_page_id, xem mục Ghim một Page vào Profile bên dưới.

Số Profile theo từng gói

Mỗi gói bao gồm một số lượng Profile cố định:

Gói	Số Profile
Starter	1
Growth	4
Business	10
Custom	Không giới hạn

Khi đạt giới hạn của gói, nâng cấp để có thêm Profile.

Tạo Profile

Trên dashboard

Vào Kết nối → Kết nối tài khoản và xác thực từng nền tảng bạn muốn đăng lên. Profile sẽ được tạo tự động, bạn không cần tự quản lý profile_id.

Qua API

Khi bắt đầu một kết nối, hệ thống sẽ tạo Profile và trả về URL kết nối (đã khoác áo thương hiệu, có thời hạn) trong cùng một lần gọi:

curl -X POST https://api.madiad.com/v1/connections/start \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "friendly_name": "Acme Coffee" }'

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "friendly_name": "Acme Coffee",
  "access_url": "https://connect.madiad.com/o/abc123def456",
  "expires_in": "48h"
}

Sử dụng profile_id (9f2b4c17-…) được trả về mỗi khi bạn đăng bài.

Bỏ qua bước chọn nền tảng

POST /v1/connections/start trả về liên kết tới trang để người dùng tự chọn nền tảng muốn kết nối. Nếu bạn muốn tự hiển thị lựa chọn đó trong giao diện của mình, hãy yêu cầu đúng một nền tảng và nhận về luôn URL cấp quyền của chính nền tảng đó:

curl -X POST https://api.madiad.com/v1/connections/start-platform \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83", "platform": "instagram" }'

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "platform": "instagram",
  "authorize_url": "https://www.instagram.com/oauth/authorize?...",
  "expires_in": 900
}

Giống /v1/connections/start, endpoint này tự tạo Profile khi bạn bỏ trống profile_id, và nhận thêm friendly_name tuỳ chọn.

authorize_url mang một state dùng một lần, hết hạn sau khoảng 15 phút (expires_in, tính bằng giây). Hãy chuyển hướng người dùng tới đó ngay, tuyệt đối không tạo sẵn rồi lưu lại, khác với liên kết 48 giờ của /v1/connections/start.

Mọi nền tảng đều khởi tạo được theo cách này, trừ Bluesky: nó xác thực bằng app password chứ không phải OAuth nên sẽ trả về 400 platform_not_startable. Với nền tảng đó hãy dùng liên kết kết nối chung.

Liệt kê Profile qua API

Có hai endpoint cùng trả về Profile. Dùng cái nào là tùy bạn có cần biết mỗi Profile đang kết nối những gì hay không.

Chỉ lấy danh sách

GET /v1/profiles trả về mọi Profile trên tài khoản, không kèm gì thêm:

curl https://api.madiad.com/v1/profiles \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profiles": [
    { "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83", "friendly_name": "Acme Coffee" },
    { "profile_id": "3d81a06f-5b24-4e97-9c1a-7f0d2e8b6a45", "friendly_name": "Acme Tea" }
  ]
}

Mỗi phần tử chỉ có đúng hai trường là profile_id và friendly_name. Danh sách sắp theo thứ tự tạo, cũ trước. Tài khoản được lấy từ chính API key nên endpoint này không nhận tham số nào và không bao giờ trả về Profile của tài khoản khác. Đây là một lệnh GET: nó không tiêu tốn lượt đăng hay phút xử lý video, chỉ tính vào rate limit theo phút. Hãy dùng endpoint này để đổ dữ liệu cho một ô chọn Profile, hoặc bất cứ khi nào bạn chỉ cần profile_id mà mọi lệnh đăng bài, kết nối và phân tích đều đòi. Nó chỉ đọc dữ liệu của chính MADIAD Hub nên trả lời nhanh, và vẫn trả lời được cả khi một nền tảng mạng xã hội đang không truy cập được.

Danh sách kèm chi tiết kết nối

GET /v1/connections/status, gọi mà bỏ trống profile_id, trả về mọi Profile cùng những nền tảng từng Profile đã nối:

curl "https://api.madiad.com/v1/connections/status" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Mỗi phần tử của mảng profiles có profile_id và friendly_name như trên, kèm thêm connected và accounts (xem chi tiết ở Kiểm tra các nền tảng đã kết nối bên dưới). Để dựng được phần chi tiết đó, lệnh phải tra cứu trực tiếp các tài khoản đã nối, nên nó chậm hơn GET /v1/profiles và có thể báo lỗi trong lúc việc tra cứu ấy không sẵn sàng. Khi chỉ cần ID thì hãy gọi GET /v1/profiles. Muốn biết còn bao nhiêu slot Profile trong gói thì gọi GET /v1/usage: trường profiles trả về used / limit / remaining.

Kết nối tài khoản mạng xã hội

Mỗi Profile bắt đầu ở trạng thái trống. Mở trang kết nối trong trình duyệt và đăng nhập vào từng nền tảng bạn muốn đăng nội dung. MADIAD Hub lưu trữ thông tin ủy quyền, vì vậy bạn không cần tự xử lý token của các nền tảng.

Mở trang kết nối

Trên dashboard, nhấn Kết nối tài khoản. Qua API, gửi cho người dùng (hoặc chính bạn) access_url được trả về từ /v1/connections/start.

Ủy quyền từng nền tảng

Đăng nhập vào Instagram, Facebook, TikTok và các nền tảng khác. Các kết nối sẽ tồn tại cho đến khi bị thu hồi.

Đăng bài

Tham chiếu Profile bằng profile_id trong mọi request đăng bài.

Các nền tảng được hỗ trợ

Một Profile có thể kết nối với bất kỳ kênh nào trong 22 kênh liệt kê ở Kênh. Trang đó cũng ghi rõ mỗi kênh nhận loại bài nào. Bài đăng chỉ thành công trên các nền tảng mà Profile đích đã thực sự kết nối. Nếu liệt kê một nền tảng chưa được kết nối, hệ thống sẽ trả về lỗi cho nền tảng đó.

Kết nối kênh nhập thủ công

Các kênh OAuth được kết nối bằng cách đăng nhập trên trang kết nối. Mười một kênh hoạt động khác: Telegram, Discord, Slack, Mastodon, Nostr, Lemmy, dev.to, Hashnode, WordPress, Whop và listmonk không có đăng nhập OAuth, nên thay vào đó bạn liên kết bot, webhook, API key hoặc application password của chính mình bằng POST /v1/connections/{kênh}. Kênh liệt kê đầy đủ trường cần cho cả mười một kênh. Hai ví dụ dưới đây cho thấy dạng chung; các kênh còn lại theo đúng dạng đó.

Telegram: dùng bot của bạn

Nhắn @BotFather trên Telegram và gửi /newbot để tạo bot. Sao chép bot token.
Thêm bot vào kênh hoặc nhóm đích với quyền quản trị viên (admin) để bot có thể đăng bài.
Trên dashboard, mở Kết nối → Telegram, dán bot token và chat ID (@tenkenh hoặc id dạng số như -100123456789), rồi kết nối.

Qua API

curl -X POST https://api.madiad.com/v1/connections/telegram \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
    "bot_token": "123456:ABC-DEF...",
    "chat_id": "@tenkenh",
    "name": "Thông báo"
  }'

Các field bắt buộc: profile_id, bot_token, chat_id. name là nhãn tùy chọn. Bot phải có quyền quản trị viên trong kênh hoặc nhóm đích. chat_id là @tenkenh hoặc id dạng số như -100123456789. Trả về 400 nếu thiếu bất kỳ field bắt buộc nào.

{
  "profiles": [
    {
      "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
      "friendly_name": "Acme Coffee",
      "connected": ["telegram"],
      "accounts": [
        { "platform": "telegram", "display_name": "Thông báo", "username": null, "avatar": null }
      ]
    }
  ]
}

Discord: webhook của kênh

Trong Discord, vào Cài đặt máy chủ → Tích hợp → Webhook → Tạo webhook, chọn kênh muốn đăng, rồi bấm Sao chép URL webhook.
Trên dashboard, mở Kết nối → Discord, dán URL webhook, rồi kết nối.

Qua API

curl -X POST https://api.madiad.com/v1/connections/discord \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
    "webhook_url": "https://discord.com/api/webhooks/...",
    "name": "Kênh marketing"
  }'

Các field bắt buộc: profile_id, webhook_url. name là nhãn tùy chọn. Trả về 400 nếu thiếu bất kỳ field bắt buộc nào.

{
  "profiles": [
    {
      "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
      "friendly_name": "Acme Coffee",
      "connected": ["discord"],
      "accounts": [
        { "platform": "discord", "display_name": "Kênh marketing", "username": null, "avatar": null }
      ]
    }
  ]
}

Các kênh nhập thủ công không nằm trong Analytics: số liệu người theo dõi, phạm vi tiếp cận và mức độ tương tác không có sẵn cho kênh nào trong nhóm này, Google Business Profile cũng vậy.

Lượt đăng không giới hạn trên mọi gói trả phí. Xử lý video vẫn có hạn mức ở nơi nó được bật, và hạn mức đó áp dụng cho cả tài khoản: mọi thương hiệu dùng chung một hạn mức hàng tháng, nên thương hiệu nào bận rộn có thể “mượn” phần của thương hiệu ít hoạt động hơn. Số Profile mới là con số cần cân nhắc khi hoạch định. Xem Mức sử dụng.

Tìm ID của Page & board

Một số nền tảng yêu cầu ID bạn cần tra cứu trước khi đăng. Dùng các endpoint sau để lấy ID đó cho một Profile.

Facebook Pages

Nếu một Profile có nhiều hơn một Facebook Page đã kết nối, truyền facebook_page_id trong request đăng bài để chọn Page muốn đăng. Liệt kê các Page khả dụng bằng:

curl "https://api.madiad.com/v1/connections/facebook/pages?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "pages": [
    { "id": "1029384756102938", "name": "Acme Coffee", "picture": "https://..." }
  ]
}

Mỗi page có id, name, và picture (URL ảnh đại diện, có thể là null). Truyền id đã chọn vào facebook_page_id khi đăng bài. Nếu Profile chỉ có đúng một Page thì tự động được chọn. Endpoint này chỉ cần dùng khi có nhiều Page. Trả về 400 nếu thiếu profile_id, 404 nếu Profile không thuộc về bạn.

LinkedIn Pages

LinkedIn đăng bài dưới danh nghĩa người dùng đã kết nối, hoặc dưới danh nghĩa một trang tổ chức mà người đó quản trị. Muốn đăng dưới danh nghĩa tổ chức thì truyền ID của trang đó vào target_linkedin_page_id (xem Tùy chọn theo nền tảng). Liệt kê các tổ chức khả dụng của một Profile bằng:

curl "https://api.madiad.com/v1/connections/linkedin/pages?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "success": true,
  "pages": [
    {
      "id": "urn:li:organization:12345678",
      "name": "Acme Coffee",
      "picture": "https://...",
      "vanityName": "acme-coffee",
      "followers": 1280
    }
  ]
}

id ở đây là URN đầy đủ dạng urn:li:organization:…, không phải một dãy số trần, nên hãy truyền nguyên văn vào target_linkedin_page_id. Bỏ trống trường đó thì bài đi dưới danh nghĩa cá nhân đã kết nối. Chỉ id và name là phần cam kết của API, các trường còn lại là thông tin phụ và có thể đổi. Trả về 409 platform_not_connected nếu Profile chưa nối tài khoản LinkedIn, và 404 not_found nếu Profile không thuộc về bạn.

Pinterest boards

Pinterest bắt buộc phải có board ID cho mỗi lần ghim. Liệt kê các board khả dụng của một Profile bằng:

curl "https://api.madiad.com/v1/connections/pinterest/boards?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "boards": [
    { "id": "987654321012345678", "name": "Seasonal Menu" }
  ]
}

Mỗi board có id và name. Truyền id đã chọn vào pinterest_board_id khi đăng bài. Field này luôn bắt buộc với Pinterest. Trả về 400 nếu thiếu profile_id, 404 nếu Profile không thuộc về bạn.

Ghim một Page vào Profile

Nối Facebook là nối một tài khoản, mà một tài khoản có thể quản trị nhiều Page; LinkedIn cũng vậy với các trang tổ chức, và Google Business với các địa điểm. Ghim một Page (hoặc địa điểm) vào Profile là cố định đích đến: mọi bài từ Profile đó đều đi tới đó, không còn chuyện rơi về Page mà tài khoản đang lấy làm mặc định.

Page đã ghim đè lên ID Page bạn gửi kèm bài đăng. Khi một Page đang được ghim vào Profile, trường facebook_page_id trong request đăng bài bị bỏ qua và bài vẫn đi tới Page đã ghim. Request vẫn báo thành công, nên không có gì trong phản hồi cho bạn biết đích đến đã đổi. LinkedIn với target_linkedin_page_id, và Google Business với gbp_location_id, cũng y như vậy. Để việc đó không xảy ra trong im lặng, bài nêu một trang hay địa điểm khác với ghim sẽ bị từ chối với 409 page_pin_conflict.Vì thế chỉ nên ghim trên Profile phục vụ một thương hiệu. Với Profile bạn cố ý dùng để đăng lên nhiều Page, hãy để trống ghim và chỉ định từng bài bằng facebook_page_id, hoặc bỏ ghim trước đã.

Bạn cũng đặt và bỏ ghim được ngay trên dashboard, trong mục Kết nối. Mọi lệnh dưới đây dùng chung cho facebook, linkedin và google_business, chỉ cần đổi tên nền tảng trong đường dẫn.

Xem Page đang ghim

curl "https://api.madiad.com/v1/connections/facebook/page?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "success": true,
  "pages": [
    { "id": "1029384756102938", "name": "Acme Coffee", "picture": "https://..." }
  ],
  "selected_page_id": "1029384756102938",
  "selected_page_name": "Acme Coffee"
}

pages là toàn bộ Page mà tài khoản đã nối có thể đăng lên. selected_page_id và selected_page_name chính là ghim hiện tại, cả hai bằng null khi chưa ghim gì. Ở biến thể LinkedIn, các id là URN dạng urn:li:organization:….

Đặt ghim

curl -X POST https://api.madiad.com/v1/connections/facebook/page \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83", "page_id": "1029384756102938" }'

Cả profile_id và page_id đều bắt buộc, thiếu page_id sẽ nhận 400 invalid_request. page_id phải là một Page mà tài khoản đã nối có quyền quản trị, hãy chọn từ danh sách pages ở trên. Phản hồi trả về đúng đối tượng như lệnh đọc, với selected_page_id đã được đặt. Ghim là thuộc tính của Profile, được đọc vào lúc bài thực sự lên sóng chứ không phải lúc bạn tạo bài, nên nó chi phối cả những bài bạn đã lên lịch từ trước.

Bỏ ghim

curl -X DELETE https://api.madiad.com/v1/connections/facebook/page \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" }'

Bỏ ghim xong thì facebook_page_id của từng bài lại là thứ quyết định đích đến.

Địa điểm Google Business

google_business ghim một địa điểm chứ không phải một trang. Lệnh đọc trả về các trường địa điểm thay cho pages:

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "success": true,
  "locations": [
    { "name": "locations/15783951491896349152", "title": "Acme Coffee Quận 1" }
  ],
  "selected_location_id": "locations/15783951491896349152",
  "selected_location_name": "Acme Coffee Quận 1"
}

Để đặt ghim, gửi name của địa điểm vào page_id (hoặc location_id). Khi tài khoản Google đã nối quản nhiều địa điểm, mỗi bài phải đi tới địa điểm đã ghim hoặc kèm gbp_location_id; nếu chỉ có một địa điểm thì không cần gì. Địa điểm đã ghim cũng là địa điểm mặc định của Profile cho phần đánh giá và phân tích.

Kiểm tra các nền tảng đã kết nối

Để xem một Profile hiện đang kết nối những nền tảng nào, gọi:

curl "https://api.madiad.com/v1/connections/status?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profiles": [
    {
      "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
      "friendly_name": "Acme Coffee",
      "connected": ["instagram", "facebook", "tiktok"],
      "accounts": [
        { "platform": "instagram", "display_name": "Acme Coffee", "username": "acmecoffee" }
      ]
    }
  ]
}

connected liệt kê slug các nền tảng đang được kết nối vào Profile, còn accounts kèm tên/handle tài khoản đã kết nối theo từng nền tảng. Bỏ profile_id để lấy trạng thái của tất cả Profile trong tài khoản. Đây là cách kiểm tra trạng thái theo yêu cầu; muốn được thông báo ngay khi một kết nối thay đổi, hãy đăng ký webhook connection.connected / connection.disconnected.

Khi nào nên dùng nhiều Profile

Agency: một Profile cho mỗi khách hàng.
Nhóm đa thương hiệu: một Profile cho mỗi thương hiệu.
Môi trường: các Profile riêng biệt cho đối tượng thử nghiệm và sản xuất.

Khi không cần thêm Profile: nhiều Facebook Page của cùng một thương hiệu, hoặc nhiều tài khoản khác nền tảng của cùng một thương hiệu. Tất cả nằm gọn trong một Profile.

Bắt đầu

Khái niệm

Tích hợp

Tham chiếu API

Số Profile theo từng gói

Tạo Profile

Trên dashboard

Qua API

Bỏ qua bước chọn nền tảng

Liệt kê Profile qua API

Chỉ lấy danh sách

Danh sách kèm chi tiết kết nối

Kết nối tài khoản mạng xã hội

Các nền tảng được hỗ trợ

Kết nối kênh nhập thủ công

Tìm ID của Page & board

Facebook Pages

LinkedIn Pages

Pinterest boards

Ghim một Page vào Profile

Xem Page đang ghim

Đặt ghim

Bỏ ghim

Địa điểm Google Business

Kiểm tra các nền tảng đã kết nối

Khi nào nên dùng nhiều Profile

​Số Profile theo từng gói

​Tạo Profile

​Trên dashboard

​Qua API

​Bỏ qua bước chọn nền tảng

​Liệt kê Profile qua API

​Chỉ lấy danh sách

​Danh sách kèm chi tiết kết nối

​Kết nối tài khoản mạng xã hội

​Các nền tảng được hỗ trợ

​Kết nối kênh nhập thủ công

​Tìm ID của Page & board

​Facebook Pages

​LinkedIn Pages

​Pinterest boards

​Ghim một Page vào Profile

​Xem Page đang ghim

​Đặt ghim

​Bỏ ghim

​Địa điểm Google Business

​Kiểm tra các nền tảng đã kết nối

​Khi nào nên dùng nhiều Profile

Số Profile theo từng gói

Tạo Profile

Trên dashboard

Qua API

Bỏ qua bước chọn nền tảng

Liệt kê Profile qua API

Chỉ lấy danh sách

Danh sách kèm chi tiết kết nối

Kết nối tài khoản mạng xã hội

Các nền tảng được hỗ trợ

Kết nối kênh nhập thủ công

Tìm ID của Page & board

Facebook Pages

LinkedIn Pages

Pinterest boards

Ghim một Page vào Profile

Xem Page đang ghim

Đặt ghim

Bỏ ghim

Địa điểm Google Business

Kiểm tra các nền tảng đã kết nối

Khi nào nên dùng nhiều Profile