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
creativevà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.
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.
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.
Cấu trúc chi tiết Parameters
campaign
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_...).
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)
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
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)
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)
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)
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)
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)
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:
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
Last updated