# 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](https://apidocs.nhanh.vn/v3/vpage/marketing/custom_audience_create) * 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](https://apidocs.nhanh.vn/v3/vpage/marketing/custom_audience_addsubscriber) * Upload ảnh lên trước để lấy imageHash của ảnh trước khi tạo chiến dịch, dùng API [Upload Image](https://apidocs.nhanh.vn/v3/vpage/marketing/fb_ad_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 ```curl curl --location 'https://vpage.open.nhanh.vn/v3.0/marketing/fmmcampaigncreate?appId={{appId}}&businessId={{businessId}}' \ --header 'Authorization: {{accessToken}}' \ --data '{ "campaign": { "pageId": "page id", "adAccountId": "act_987654321", "segmentIds": [], "name": "fmm message", "budget": 200000, "budgetType": "life_time", "adStartAt": 1761294919, "adEndAt": 1761813319 }, "settings": { "noResendWithinDays": 1, "excludes": { "topicsIds": [], "audienceIds": [], "campaignIds": [] } }, "message": { "greeting": "welcome", "attachments": [ { "name": "Welcome!", "imageHash": "63d13607cd76dc3fba71350751352d85", "description": "We have the right hat for everyone.", "link": "https://vpage.nhanh.vn", "buttons": [ { "type": "URL", "url": "https://vpage.nhanh.vn", "text": "View Website" }, { "type": "SCRIPT", "text": "Start Chatting", "blockId": "", "botId": "" }, { "type": "CART", "text": "View cart", "cartId": "" } ] } ] } }' ``` ### campaign | Key | Type | Description | | ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pageId | string | ID của Trang (Page) Facebook sẽ dùng để gửi tin nhắn. | | adAccountId | string | ID của Tài khoản Quảng cáo (Ad Account ID) liên kết. (Format: act\_...). | | segmentIds | array | Danh sách ID tệp [đối tượng tuỳ chỉnh (Custom Audience)](https://apidocs.nhanh.vn/v3/vpage/marketing/custom_audience_list) hoặc [Chủ đề (Topic)](https://apidocs.nhanh.vn/v3/vpage/marketing/topic_list) | | name | string | Tên của chiến dịch. | | budget | number | Ngân sách cho chiến dịch (theo budgetType). | | budgetType | string |

Loại ngân sách áp dụng:
life\_time: Ngân sách toàn chiến dịch.
daily: Ngân sách mỗi ngày.

| | adStartAt | number | Thời gian bắt đầu chiến dịch (Unix Timestamp). | | adEndAt | number | Thời gian kết thúc chiến dịch (Unix Timestamp). | ### settings | 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 | Không gửi cho khách đã đăng ký [Chủ đề (Topic)](https://apidocs.nhanh.vn/v3/vpage/marketing/topic_list) | | excludes.audienceIds | array | Không gửi cho khách trong các tệp [đối tượng tuỳ chỉnh (Custom Audience)](https://apidocs.nhanh.vn/v3/vpage/marketing/custom_audience_list) | | excludes.campaignIds | array | Không gửi cho khách đã gửi trong [chiến dịch](https://apidocs.nhanh.vn/v3/vpage/marketing/fmm_campaign_list) | ### message | Key | Optional | Type | Description | | ----------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | | greeting | optional | string |

Lời chào mở đầu.
Giới hạn 160 kí tự.

| | attachments | required | array | Mảng chứa một hoặc nhiều phần tử tin nhắn. Giới hạn tối đa là 10 phần tử. | | configCart | optional | json |

(Chỉ áp dụng khi có button có type = CART trong attachments)
Cấu hình tin nhắn mồi khi gửi giỏ hàng.

| ### attachments | Key | Optional | Type | Description | | ----------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------- | | name | required | string |

Tiêu đề của card tin nhắn.
Giới hạn 80 kí tự .

| | url | optional | string |

URL của hình ảnh hiển thị trên card. Bắt buộc phải là HTTPS.
Giới hạn 120 kí tự.

| | imageHash | required | string | imageHash của hình ảnh sử dụng API [Upload Image](https://apidocs.nhanh.vn/v3/vpage/marketing/fb_ad_upload_image) | | description | optional | string |

Nội dung/Phụ đề của card.
Hiển thị dưới tiêu đề. Giới hạn 640 kí tự.

| | link | optional | string | URL mặc định được mở khi người dùng nhấp vào bất kỳ đâu trên card (trừ nút bấm). | | buttons | optional | array | Mảng chứa các nút bấm tương tác (CTA) cho card này. Tối đa 3 nút/card. | ### buttons | Key | Type | Description | | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | type | string |

Loại hành động của nút
URL: Mở liên kết.
SCRIPT: Chạy kịch bản chatbot.
CART: Mở giỏ hàng

| | text | string | Văn bản hiển thị trên nút bấm. | | url | string | (Chỉ áp dụng cho type: URL) URL sẽ được mở khi người dùng nhấp vào nút. | | botId | string | (Chỉ áp dụng cho type: SCRIPT) ID của Chatbot. | | blockId | string | (Chỉ áp dụng cho type: SCRIPT) ID Kịch bản của Chatbot sẽ được kích hoạt khi người dùng nhấp vào nút. | | cartId | string | (Chỉ áp dụng cho type: CART) ID Giỏ hàng. | | productId | string | optional (Chỉ áp dụng cho type: CART) ID sản phẩm trong giỏ hàng. | ### configCart | Key | Type | Description | | ----------- | ------ | --------------------------------------------------------------------------- | | seedStatus | number |

Bật tắt tin nhắn mồi
1: bật.
2: tắt.

| | seedLabel | string |

Tiêu đề button gửi link giỏ hàng.
Giới hạn 80 kí tự.

| | seedMessage | string |

Nội dung gửi.
Giới hạn 640 kí tự.

| ## Response * Xem cấu trúc chung [tại đây](https://apidocs.nhanh.vn/v3/readme#response). ### Failed response * Xem các mã lỗi chung [tại đây](https://apidocs.nhanh.vn/v3/readme#failed-response). * Danh sách **errorCode** của riêng API này: | errorCode | Description | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------- | | ERR\_FMM\_INVALID\_EXCLUDE\_SEGMENT\_IDS | Sai điều kiện loại trừ tệp. VD bạn đang 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", } } ```