> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madiad.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Profiles

> Mô hình hóa từng thương hiệu, khách hàng hoặc tài khoản con thành một Profile.

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:

```bash theme={null}
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" }'
```

```json theme={null}
{
  "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 đó:

```bash theme={null}
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" }'
```

```json theme={null}
{
  "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.

<Warning>
  `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`.
</Warning>

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:

```bash theme={null}
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](#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`](/vi/concepts/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.

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Ủ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.
  </Step>

  <Step title="Đăng bài">
    Tham chiếu Profile bằng `profile_id` trong mọi request đăng bài.
  </Step>
</Steps>

## 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:

<AccordionGroup>
  <Accordion title="Telegram: dùng bot của bạn">
    1. Nhắn **@BotFather** trên Telegram và gửi `/newbot` để tạo bot. Sao chép **bot token**.
    2. 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.
    3. 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**

    ```bash theme={null}
    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.

    ```json theme={null}
    {
      "profiles": [
        {
          "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
          "friendly_name": "Acme Coffee",
          "connected": ["telegram"],
          "accounts": [
            { "platform": "telegram", "display_name": "Thông báo", "username": null, "avatar": null }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Discord: webhook của kênh">
    1. 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**.
    2. Trên dashboard, mở **Kết nối → Discord**, dán **URL webhook**, rồi kết nối.

    **Qua API**

    ```bash theme={null}
    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.

    ```json theme={null}
    {
      "profiles": [
        {
          "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
          "friendly_name": "Acme Coffee",
          "connected": ["discord"],
          "accounts": [
            { "platform": "discord", "display_name": "Kênh marketing", "username": null, "avatar": null }
          ]
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  Telegram và Discord **không** nằm trong [Analytics](/vi/concepts/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.
</Note>

<Note>
  **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](/vi/concepts/usage).
</Note>

## 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:

```bash theme={null}
curl "https://api.madiad.com/v1/connections/facebook/pages?profile_id=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

```json theme={null}
{
  "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:

```bash theme={null}
curl "https://api.madiad.com/v1/connections/pinterest/boards?profile_id=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

```json theme={null}
{
  "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:

```bash theme={null}
curl "https://api.madiad.com/v1/connections/status?profile_id=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

```json theme={null}
{
  "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](/vi/concepts/webhooks) `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.