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

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) hoặc Chủ đề (Topic)
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)
excludes.audienceIds	array	Không gửi cho khách trong các tệp đối tượng tuỳ chỉnh (Custom Audience)
excludes.campaignIds	array	Không gửi cho khách đã gửi trong chiến dịch

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

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

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