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 (prof_…) 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, TikTok
├── Profile: Acme Tea      → Instagram, X
└── Profile: Khách hàng — Nova → LinkedIn, YouTube

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": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "friendly_name": "Acme Coffee",
  "access_url": "https://connect.madiad.com/o/abc123def456",
  "expires_in": "48h"
}

Sử dụng profile_id (prof_…) đượ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": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z", "platform": "instagram" }'

{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "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ần lấy danh sách toàn bộ Profile trên tài khoản (kèm những nền tảng mỗi Profile đã kết nối)? Gọi GET /v1/connections/status và bỏ trống profile_id. Không có endpoint /v1/profiles riêng, đây chính là cách liệt kê Profile:

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

Trả về mảng profiles, mỗi phần tử có profile_id, friendly_name, connected và accounts (xem chi tiết ở Kiểm tra các nền tảng đã kết nối bên dưới). 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ỳ nền tảng nào trong số sau: TikTok, Instagram, YouTube, Facebook, LinkedIn, X, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, Telegram và Discord. 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 Telegram & Discord

TikTok, Instagram và chín nền tảng còn lại được kết nối bằng cách đăng nhập trên trang kết nối. Telegram và Discord hoạt động khác: chúng không có đăng nhập OAuth, nên thay vào đó bạn liên kết bot hoặc webhook kênh của riêng mình:

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": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
    "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": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
      "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": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
    "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": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
      "friendly_name": "Acme Coffee",
      "connected": ["discord"],
      "accounts": [
        { "platform": "discord", "display_name": "Kênh marketing", "username": null, "avatar": null }
      ]
    }
  ]
}

Telegram và Discord 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 hai nền tảng này.

Lượt đăng không giới hạn trên mọi gói trả phí. Phút FFmpeg vẫn có 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=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "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.

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=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "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.

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=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profiles": [
    {
      "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
      "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.

Bắt đầu

Khái niệm

Tích hợp

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

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 Telegram & Discord

Tìm ID của Page & board

Facebook Pages

Pinterest boards

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

​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 Telegram & Discord

​Tìm ID của Page & board

​Facebook Pages

​Pinterest boards

​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

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 Telegram & Discord

Tìm ID của Page & board

Facebook Pages

Pinterest boards

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

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