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
- 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
- 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
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 --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 --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 --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 --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 hoặc Chủ đề. 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

Loại gửi chiến dịch. Bắt buộc. Chấp nhận: creative: Mẫu tin cơ bản (Gửi ảnh và nút bấm mặc định). template: Mẫu tin nâng cao (Carousel mẫu tin nhắn kèm Quick Replies). product: Gửi danh sách sản phẩm từ Meta catalog. coupon: Gửi voucher giảm giá.

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. 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

Loại hành động của nút. Bắt buộc. Chấp nhận: URL: Mở liên kết. SCRIPT: Chạy kịch bản chatbot. CART: Mở giỏ hàng thanh toán.

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

Loại nút phản hồi nhanh. Bắt buộc. Chấp nhận: text: Nút văn bản tùy chỉnh. email: Tự điền Email FB của user. phone: Tự điền Số điện thoại của user.

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.

Failed response

Xem các mã lỗi chung tại đây.
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

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

PreviousUpload Facebook Ad image NextGửi lại một chiến dịch Facebook Marketing Message

Last updated 7 days ago

Request

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

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

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

4. Gửi Coupon / Voucher (coupon)

Cấu trúc chi tiết Parameters

campaign

settings (tùy chọn)

message

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

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

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

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

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

Response

Failed response

Successful response

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

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

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

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

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

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

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

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

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