> For the complete documentation index, see [llms.txt](https://apidocs.nhanh.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.nhanh.vn/v3/vpage/marketing/fmm_campaign_create.md).

# Gửi Facebook Marketing Message

* API này dùng để tạo chiến dịch gửi Facebook Marketing Message. Để gửi được tin, bạn cần bắt đầu bằng việc:
  * Đăng nhập vào Vpage để kết nối tài khoản quảng cáo.
  * Tạo tệp đối tượng tùy chỉnh ở trên Vpage hoặc dùng API [Tạo tệp đối tượng tùy chỉnh](/v3/vpage/marketing/custom_audience_create.md)
  * Upload khách hàng vào tệp đối tượng tùy chỉnh hoặc dùng API [Thêm khách hàng vào tệp đối tượng tùy chỉnh](/v3/vpage/marketing/custom_audience_addsubscriber.md)
  * Upload ảnh lên trước để lấy imageHash của ảnh trước khi tạo chiến dịch (đối với loại `creative` và `template`), dùng API [Upload Image](/v3/vpage/marketing/fb_ad_upload_image.md)
* **Chú ý**:
  * Facebook giới hạn mỗi user chỉ được nhận 1 tin nhắn quảng cáo trong vòng 12h, nếu bạn vi phạm quy định này, page của bạn có thể sẽ bị khóa tính năng gửi Marketing Message.
  * Vpage sẽ tự động chặn việc bạn gửi spam quá nhiều bằng cách loại trừ các user token đã nhận được tin trong vòng 12h gần nhất. Cơ chế này chỉ hoạt động được khi bạn chỉ sử dụng Vpage để gửi tin, nếu bạn dùng thêm 1 app khác, Vpage không thể đảm bảo được việc này.
  * Thời gian Facebook phản hồi API này khá chậm: Có thể \~10 giây.

## Request

### 1. Gửi loại Mẫu tin cơ bản (`creative`)

Gửi tin nhắn dạng carousel với ảnh và nút bấm. Hỗ trợ từ 1 đến 10 card. Mỗi card bắt buộc phải có `imageHash` (lấy từ API Upload Image) và `link` (URL đích).

```curl
curl --location 'https://vpage.open.nhanh.vn/v3.0/marketing/fmmcampaigncreate?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
  "campaign": {
    "pageId": "167890463074771",
    "adAccountId": "act_962587495564547",
    "segmentIds": [
      "120246391779940373",
      "I_pgtJ0Bq4rJK0SlQsHD"
    ],
    "name": "Chiến dịch Mẫu tin cơ bản",
    "budget": 100000,
    "budgetType": "life_time",
    "adStartAt": 1790000000,
    "adEndAt": 1790086400,
    "type": "creative"
  },
  "settings": {
    "noResendWithinDays": 7,
    "excludes": {
      "topicsIds": [],
      "audienceIds": [],
      "campaignIds": []
    }
  },
  "message": {
    "greeting": "Xin chào {{first_name}}! Xem ngay các sản phẩm mới nhất của chúng tôi.",
    "attachments": [
      {
        "imageHash": "63d13607cd76dc3fba71350751352d85",
        "name": "Áo Khoác Nam Bomber",
        "description": "Chất liệu phao ấm áp, thiết kế năng động trẻ trung.",
        "link": "https://vpage.nhanh.vn/",
        "buttons": [
          {
            "type": "URL",
            "text": "Xem sản phẩm",
            "url": "https://vpage.nhanh.vn/"
          },
          {
            "type": "SCRIPT",
            "text": "Trò chuyện trực tiếp",
            "botId": "iTLPoJoBMexIgwsbLJX0",
            "blockId": "DUMv6JoBMexIgwsbbyew"
          }
        ]
      },
      {
        "imageHash": "ba9785f4bf57867b772399507eaf9b93",
        "name": "Quần Jeans Slimfit",
        "description": "Co giãn tốt, giữ form dáng cực chuẩn.",
        "link": "https://vpage.nhanh.vn/",
        "buttons": [
          {
            "type": "URL",
            "text": "Mua ngay",
            "url": "https://vpage.nhanh.vn/"
          }
        ]
      }
    ]
  }
}'
```

### 2. Gửi loại Mẫu tin nâng cao (`template`)

Gửi tin nhắn dạng carousel kèm Quick Replies (nút phản hồi nhanh). Hỗ trợ từ 1 đến 10 card. Quick Reply loại `text` bắt buộc phải có `botId` và `blockId`.

```curl
curl --location 'https://vpage.open.nhanh.vn/v3.0/marketing/fmmcampaigncreate?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
  "campaign": {
    "pageId": "167890463074771",
    "adAccountId": "act_962587495564547",
    "segmentIds": [
      "120246391779940373",
      "I_pgtJ0Bq4rJK0SlQsHD"
    ],
    "name": "Chiến dịch Mẫu tin nâng cao",
    "budget": 150000,
    "budgetType": "life_time",
    "adStartAt": 1790000000,
    "adEndAt": 1790172800,
    "type": "template"
  },
  "settings": {
    "noResendWithinDays": 3
  },
  "message": {
    "greeting": "Chúc mừng bạn nhận được ưu đãi độc quyền!",
    "attachments": [
      {
        "imageHash": "63d13607cd76dc3fba71350751352d85",
        "url": "https://chatcdn.nvndev.net/page/733971813141805/20260530/626fa98240562bc843d9fbf8d90a22ee.png",
        "name": "Voucher Giảm 50K",
        "description": "Áp dụng cho đơn hàng bất kì từ 300K.",
        "link": "https://vpage.nhanh.vn/",
        "buttons": [
          {
            "type": "URL",
            "text": "Truy cập ngay",
            "url": "https://vpage.nhanh.vn/"
          }
        ]
      }
    ],
    "quickReplies": [
      {
        "type": "text",
        "title": "Nhận tư vấn ngay",
        "botId": "iTLPoJoBMexIgwsbLJX0",
        "blockId": "DUMv6JoBMexIgwsbbyew"
      },
      {
        "type": "phone"
      }
    ]
  }
}'
```

### 3. Gửi danh sách sản phẩm (`product`)

Gửi danh sách sản phẩm từ Meta catalog. Không cần `attachments`, chỉ cần truyền mảng `productIds`. Tối đa 10 sản phẩm.

```curl
curl --location 'https://vpage.open.nhanh.vn/v3.0/marketing/fmmcampaigncreate?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
  "campaign": {
    "pageId": "167890463074771",
    "adAccountId": "act_962587495564547",
    "segmentIds": [
      "120246391779940373",
      "I_pgtJ0Bq4rJK0SlQsHD"
    ],
    "name": "Chiến dịch Gửi Sản Phẩm",
    "budget": 200000,
    "budgetType": "daily",
    "adStartAt": 1790000000,
    "adEndAt": 1790086400,
    "type": "product"
  },
  "message": {
    "productIds": [
      "35992283650387505",
      "24931185889837761"
    ]
  }
}'
```

### 4. Gửi Coupon / Voucher (`coupon`)

Gửi tin nhắn voucher/mã giảm giá. Bắt buộc phải có đúng 1 phần tử trong mảng `attachments` chứa thông tin voucher. Trường `url` là link hình ảnh HTTPS hiển thị trên voucher.

```curl
curl --location 'https://vpage.open.nhanh.vn/v3.0/marketing/fmmcampaigncreate?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
  "campaign": {
    "pageId": "167890463074771",
    "adAccountId": "act_962587495564547",
    "segmentIds": [
      "120246391779940373",
      "I_pgtJ0Bq4rJK0SlQsHD"
    ],
    "name": "Chiến dịch Tặng Coupon",
    "budget": 120000,
    "budgetType": "daily",
    "adStartAt": 1790000000,
    "adEndAt": 1790086400,
    "type": "coupon"
  },
  "message": {
    "greeting": "Ưu đãi chào Hè dành riêng cho bạn!",
    "attachments": [
      {
        "name": "Voucher Giảm 10% Toàn Bộ Cửa Hàng",
        "coupon_code": "HEVUI10",
        "link": "https://vpage.nhanh.vn/",
        "coupon_url_button_title": "Mua Sắm Ngay",
        "url": "https://chatcdn.nvndev.net/page/733971813141805/20260530/626fa98240562bc843d9fbf8d90a22ee.png",
        "description": "Mã giảm giá có hiệu lực đến hết năm nay.",
        "expire_time": 1798732799
      }
    ]
  }
}'
```

***

## Cấu trúc chi tiết Parameters

### campaign

| Key         | Type   | Description                                                                                                                                                                                                                                                                                                                   |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pageId      | string | ID của Trang (Page) Facebook sẽ dùng để gửi tin nhắn. Bắt buộc.                                                                                                                                                                                                                                                               |
| adAccountId | string | ID của Tài khoản Quảng cáo (Ad Account ID) liên kết. Bắt buộc. (Format: `act_...`).                                                                                                                                                                                                                                           |
| segmentIds  | array  | Danh sách ID tệp [đối tượng tuỳ chỉnh](/v3/vpage/marketing/custom_audience_list.md) hoặc [Chủ đề](/v3/vpage/marketing/topic_list.md). Bắt buộc. Tối đa 50 phần tử.                                                                                                                                                            |
| name        | string | Tên của chiến dịch. Bắt buộc. Không được rỗng.                                                                                                                                                                                                                                                                                |
| budget      | number | Ngân sách cho chiến dịch (đơn vị VNĐ). Bắt buộc. Tối thiểu `50000`.                                                                                                                                                                                                                                                           |
| budgetType  | string | Loại ngân sách: `daily` (mỗi ngày) hoặc `life_time` (toàn chiến dịch). Bắt buộc.                                                                                                                                                                                                                                              |
| adStartAt   | number | Thời gian bắt đầu chiến dịch (Unix Timestamp). Bắt buộc. Phải ở **tương lai** (không được nhỏ hơn thời điểm hiện tại).                                                                                                                                                                                                        |
| adEndAt     | number | Thời gian kết thúc chiến dịch (Unix Timestamp). Bắt buộc. Phải lớn hơn `adStartAt`.                                                                                                                                                                                                                                           |
| type        | string | <p>Loại gửi chiến dịch. Bắt buộc. Chấp nhận:<br><code>creative</code>: Mẫu tin cơ bản (Gửi ảnh và nút bấm mặc định).<br><code>template</code>: Mẫu tin nâng cao (Carousel mẫu tin nhắn kèm Quick Replies).<br><code>product</code>: Gửi danh sách sản phẩm từ Meta catalog.<br><code>coupon</code>: Gửi voucher giảm giá.</p> |

### settings (tùy chọn)

| Key                  | Type   | Description                                                                                             |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| noResendWithinDays   | number | Không gửi cho khách đã nhận tin trong vòng x ngày gần nhất.                                             |
| excludes.topicsIds   | array  | Danh sách ID Chủ đề để loại trừ. Tối đa 50 phần tử. Không được trùng với `segmentIds`.                  |
| excludes.audienceIds | array  | Danh sách ID tệp đối tượng tùy chỉnh để loại trừ. Tối đa 50 phần tử. Không được trùng với `segmentIds`. |
| excludes.campaignIds | array  | Danh sách ID chiến dịch để loại trừ (không gửi cho khách đã nhận tin trước đó). Tối đa 50 phần tử.      |

### message

| Key          | Optional    | Type   | Description                                                                                                                                                     |
| ------------ | ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| greeting     | optional    | string | Lời chào mở đầu. Giới hạn 160 kí tự. (Áp dụng cho: `creative`, `template`, `coupon`). Không áp dụng cho `product`.                                              |
| attachments  | conditional | array  | Mảng chứa thông tin card tin nhắn. **Bắt buộc** với `creative` (1–10 card), `template` (1–10 card), và `coupon` (đúng 1 phần tử). **Không dùng** cho `product`. |
| productIds   | conditional | array  | Mảng chứa danh sách ID sản phẩm từ Meta catalog. **Bắt buộc** với loại `product`. Tối đa 10 phần tử. Mỗi phần tử phải là string hoặc số.                        |
| quickReplies | optional    | array  | Mảng nút phản hồi nhanh hiển thị bên dưới tin nhắn. Tối đa 13 phần tử. (Chỉ áp dụng cho loại: `template`).                                                      |
| configCart   | optional    | object | Cấu hình tin nhắn mồi khi gửi giỏ hàng. Chỉ áp dụng khi có nút bấm type `CART` trong `attachments` của loại `creative` hoặc `template`.                         |

### attachments (Dành cho loại: `creative`, `template`)

| Key         | Optional    | Type   | Description                                                                                                                                                                                                                                        |
| ----------- | ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| imageHash   | required    | string | Hash của ảnh đã upload qua API [Upload Image](/v3/vpage/marketing/fb_ad_upload_image.md). Bắt buộc để tạo ad creative.                                                                                                                             |
| url         | conditional | string | URL hình ảnh hiển thị trên card (phải là URL HTTPS hợp lệ). **Bắt buộc** đối với loại `template` (để hiển thị ảnh khi gửi tin thật qua Messenger API), **tùy chọn** đối với loại `creative` (Meta tự động lấy ảnh từ `imageHash` của ad creative). |
| name        | required    | string | Tiêu đề của card tin nhắn. Giới hạn 80 kí tự.                                                                                                                                                                                                      |
| link        | conditional | string | URL đích mở ra khi người dùng nhấp vào card (trừ các nút bấm CTA). **Bắt buộc** với `creative`, tùy chọn với `template`. Phải là URL hợp lệ. Giới hạn 120 kí tự.                                                                                   |
| description | optional    | string | Nội dung phụ đề hiển thị dưới tiêu đề card. Giới hạn 640 kí tự với `creative`, 80 kí tự với `template`.                                                                                                                                            |
| buttons     | optional    | array  | Mảng chứa tối đa 3 nút bấm tương tác (CTA) cho card này.                                                                                                                                                                                           |

### attachments (Dành riêng cho loại: `coupon`)

| Key                        | Optional | Type   | Description                                                                                     |
| -------------------------- | -------- | ------ | ----------------------------------------------------------------------------------------------- |
| name                       | required | string | Tiêu đề của voucher. Giới hạn 80 kí tự.                                                         |
| coupon\_code               | required | string | Mã giảm giá để người dùng sao chép và áp dụng.                                                  |
| link                       | required | string | URL đích chuyển hướng khi click nút mua hàng. Phải bắt đầu bằng `https://`.                     |
| coupon\_url\_button\_title | required | string | Tiêu đề hiển thị trên nút bấm nhận/áp dụng coupon.                                              |
| url                        | required | string | URL hình ảnh voucher hiển thị trong tin nhắn (phải là link ảnh HTTPS).                          |
| description                | optional | string | Mô tả hoặc điều kiện áp dụng voucher. Giới hạn 80 kí tự.                                        |
| expire\_time               | optional | number | Thời gian hết hạn voucher (Unix Timestamp, số nguyên dương). Hiển thị đếm ngược cho người nhận. |

### buttons (Trong card của attachments — loại `creative`, `template`)

| Key        | Type   | Description                                                                                                                                                                                                                  |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type       | string | <p>Loại hành động của nút. Bắt buộc. Chấp nhận:<br><code>URL</code>: Mở liên kết.<br><code>SCRIPT</code>: Chạy kịch bản chatbot.<br><code>CART</code>: Mở giỏ hàng thanh toán.</p>                                           |
| text       | string | Văn bản hiển thị trên nút bấm. Bắt buộc.                                                                                                                                                                                     |
| url        | string | URL liên kết đích. Bắt buộc khi type là `URL`. Phải là URL hợp lệ. Giới hạn 120 kí tự.                                                                                                                                       |
| botId      | string | ID của Chatbot. Bắt buộc khi type là `SCRIPT`.                                                                                                                                                                               |
| blockId    | string | ID Kịch bản Chatbot. Bắt buộc khi type là `SCRIPT`. (Lưu ý: Hệ thống sẽ tự động truy vấn và điền trường `alias` dựa trên `blockId` để cấu hình chính xác cho chatbot trên Facebook, người dùng không cần tự truyền `alias`). |
| cartId     | string | ID Giỏ hàng. Bắt buộc khi type là `CART`.                                                                                                                                                                                    |
| productIds | array  | Mảng danh sách ID sản phẩm được thêm vào giỏ hàng. Tùy chọn, chỉ áp dụng khi type là `CART`.                                                                                                                                 |

### quickReplies (Trong message — chỉ loại `template`)

| Key        | Type   | Description                                                                                                                                                                                                |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type       | string | <p>Loại nút phản hồi nhanh. Bắt buộc. Chấp nhận:<br><code>text</code>: Nút văn bản tùy chỉnh.<br><code>email</code>: Tự điền Email FB của user.<br><code>phone</code>: Tự điền Số điện thoại của user.</p> |
| title      | string | Văn bản hiển thị trên nút. Bắt buộc khi type là `text`. Giới hạn 20 kí tự.                                                                                                                                 |
| botId      | string | ID của Chatbot kích hoạt khi nhấn. Bắt buộc khi type là `text`.                                                                                                                                            |
| blockId    | string | ID Kịch bản Chatbot kích hoạt khi nhấn. Bắt buộc khi type là `text`.                                                                                                                                       |
| image\_url | string | URL hình ảnh icon bên cạnh văn bản nút. Tùy chọn, chỉ áp dụng khi type là `text`.                                                                                                                          |

### configCart (Tùy chọn — chỉ khi có nút `CART`)

| Key         | Type   | Description                                                                       |
| ----------- | ------ | --------------------------------------------------------------------------------- |
| seedStatus  | number | Bật/tắt tin nhắn mồi: `1` = bật (Active), `2` = tắt (Inactive). Bắt buộc.         |
| seedLabel   | string | Tiêu đề nút giỏ hàng. Bắt buộc khi `seedStatus = 1`. Giới hạn 80 kí tự.           |
| seedMessage | string | Nội dung gửi kèm nút giỏ hàng. Bắt buộc khi `seedStatus = 1`. Giới hạn 640 kí tự. |

***

## Response

* Xem cấu trúc chung [tại đây](/v3/readme.md#response).

### Failed response

* Xem các mã lỗi chung [tại đây](/v3/readme.md#failed-response).
* Danh sách **errorCode** của riêng API này:

| errorCode                                | Description                                                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| ERR\_INVALID\_FORM\_FIELDS               | Dữ liệu gửi lên không hợp lệ. Chi tiết lỗi sẽ trả về trong trường `messages` với key tương ứng.         |
| ERR\_FMM\_INVALID\_EXCLUDE\_SEGMENT\_IDS | Sai điều kiện loại trừ tệp. Ví dụ: Bạn chọn gửi tin cho tệp A, nhưng lại chọn loại trừ chính tệp A này. |

### Successful response

```json
{
  "code": 1,
  "data": {
      "adCampaignId": "(string) Id of Facebook Marketing Message campaign",
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.nhanh.vn/v3/vpage/marketing/fmm_campaign_create.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.