Tạo và quản lý mẫu

Mẫu được sử dụng khi gửi mẫu tin nhắn bằng API Đám mây, do Meta cung cấp hoặc API Tại chỗ. API Đám mây xem xét các mẫu và thông số biến bằng công nghệ máy học để bảo vệ tính bảo mật và tính toàn vẹn của dịch vụ API Đám mây. Khi API Đám mây xem xét các mẫu và văn bản biến, hệ thống sẽ không chia sẻ thông tin với WhatsApp.

Bạn có thể tạo mẫu bằng API Quản lý doanh nghiệp hoặc Trình quản lý WhatsApp Business. Số lượng mẫu mà một Tài khoản WhatsApp Business có thể có được xác định theo doanh nghiệp mẹ của tài khoản đó. Nếu doanh nghiệp mẹ chưa được xác minh, mỗi Tài khoản WhatsApp Business của doanh nghiệp này sẽ chỉ có 250 mẫu. Tuy nhiên, nếu doanh nghiệp mẹ đã được xác minh và ít nhất một Tài khoản WhatsApp Business của doanh nghiệp này sở hữu số điện thoại doanh nghiệp có tên hiển thị đã được phê duyệt, mỗi Tài khoản WhatsApp Business của doanh nghiệp có thể có tối đa 6.000 mẫu.

Trước khi bắt đầu

Bạn sẽ cần có:

• Mã truy cập dành cho Người dùng hệ thống được liên kết với doanh nghiệp
• Quyền whatsapp_business_management
• ID Tài khoản WhatsApp Business của doanh nghiệp
• Tên người dùng tài sản file phương tiện của file tài liệu, hình ảnh hoặc video bất kỳ cần sử dụng trong mẫu có file phương tiện. Để lấy tên người dùng tài sản file phương tiện, bạn phải tải lên tài sản file phương tiện qua API Tải lên nối tiếp.

Giới hạn

• Trường tên mẫu tin nhắn có giới hạn là 512 ký tự.
• Trường nội dung mẫu tin nhắn có giới hạn là 1024 ký tự.
• Bạn chỉ có thể chỉnh sửa khi mẫu ở trạng thái Đã phê duyệt, Bị từ chối hoặc Bị tạm dừng. Bạn có thể chỉnh sửa mẫu một lần mỗi ngày, tối đa 10 lần mỗi tháng.
• Mỗi giờ, Tài khoản WhatsApp Business chỉ có thể tạo 100 mẫu tin nhắn.
• Đối với mẫu có 4 nút trở lên hoặc một nút câu trả lời nhanh và ít nhất một nút thuộc loại khác, người dùng không thể xem mẫu trên ứng dụng WhatsApp dành cho máy tính. Những người dùng WhatsApp nhận được 1 trong các mẫu tin nhắn này sẽ được nhắc xem tin nhắn trên điện thoại.

Bản địa hóa

Bạn có thể thêm mẫu tin nhắn bằng một ngôn ngữ cụ thể khi tạo mẫu. Các mẫu này được tính vào giới hạn của bạn. Đảm bảo tính nhất quán khi cung cấp bản dịch. Hãy xem bài viết Tại sao tôi gặp lỗi "không có cấu trúc" trong lệnh gọi lại? trong trung tâm trợ giúp để biết thêm thông tin.

Tạo mẫu

Gửi yêu cầu POST đến điểm cuối Tài khoản WhatsApp Business > Mẫu tin nhắn để tạo mẫu.

Cú pháp yêu cầu

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

Nội dung yêu cầu POST

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": <ALLOW_CATEGORY_CHANGE>,
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

Thuộc tính nội dung

Hạng mục mẫu

Mẫu phải được phân loại là một trong những hạng mục sau đây. Hạng mục được xem xét khi định giá và hạng mục bạn chỉ định sẽ được xác thực khi tạo mẫu.

• AUTHENTICATION
• MARKETING
• UTILITY

Hãy tham khảo tài liệu về Phân loại mẫu của chúng tôi để xác định hạng mục sẽ sử dụng khi tạo mẫu.

Thành phần của mẫu

Mẫu bao gồm các thành phần tương tác, văn bản và file phương tiện khác nhau, tùy thuộc vào nhu cầu của doanh nghiệp bạn. Hãy tham khảo tài liệu về Thành phần mẫu để biết danh sách tất cả những thành phần có thể sử dụng cùng với các yêu cầu của thành phần đó, cũng như mẫu và truy vấn mẫu.

Khi tạo một mẫu, hãy xác định các thành phần của mẫu đó bằng cách chỉ định một mảng đối tượng thành phần cho thuộc tính thành phần trong phần nội dung yêu cầu.

Ví dụ: dưới đây là một mảng chứa thành phần nội dung văn bản có 2 biến và giá trị mẫu, thành phần nút số điện thoại và thành phần nút URL:

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
    "example": {
      "body_text": [
        [
          "Pablo","860198-230332"
        ]
      ]
    }
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "PHONE_NUMBER",
        "text": "Call",
        "phone_number": "15550051310"
      },
      {
        "type": "URL",
        "text": "Contact Support",
        "url": "https://www.luckyshrub.com/support"
      }
    ]
  }
]

Hãy tham khảo tài liệu về Thành phần mẫu để biết danh sách tất cả những thành phần có thể sử dụng cùng với các yêu cầu của thành phần đó, cũng như mẫu và truy vấn mẫu.

Lưu ý rằng các mẫu được phân loại là AUTHENTICATION có các yêu cầu về thành phần duy nhất. Hãy xem phần Mẫu xác thực.

Xác thực hạng mục

Khi bạn gửi yêu cầu tạo mẫu, chúng tôi sẽ lập tức xác thực hạng mục của mẫu dựa trên nguyên tắc phân loại mẫu.

• Nếu đồng ý với hạng mục mà bạn đã chỉ định, chúng tôi sẽ tạo mẫu và đặt status của mẫu thành PENDING. Sau đó, mẫu sẽ trải qua quy trình xét duyệt mẫu.
• Nếu không đồng ý với hạng mục bạn chỉ định, chúng tôi sẽ tạo mẫu, nhưng đặt status của mẫu thành REJECTED và kích hoạt webhook cập nhật trạng thái mẫu tin nhắn với reason được đặt thành INCORRECT_CATEGORY. Bạn nên theo dõi webhook này để xác định các mẫu bị từ chối hoặc yêu cầu trường rejected_reason trên mẫu mới tạo, trường này sẽ có giá trị là TAG_CONTENT_MISMATCH.

Trong cả hai trường hợp, trạng thái ban đầu của mẫu được trả về trong phản hồi API.

Nếu trạng thái mẫu đã được đặt thành REJECTED trong quá trình xác thực hạng mục, bạn có các tùy chọn sau:

• Chỉnh sửa các thành phần của mẫu để phù hợp với nguyên tắc của chúng tôi.
• Chỉnh sửa hạng mục của mẫu để phù hợp với nguyên tắc của chúng tôi.
• Tạo mẫu mới.

Phân loại tự động

Bạn có thể thêm thuộc tính allow_category_change vào yêu cầu để chúng tôi có thể tự động chỉ định hạng mục dựa trên nội dung mẫu và nguyên tắc phân loại mẫu của chúng tôi. Nhờ vậy, trạng thái của mẫu có thể tránh bị đặt ngay thành REJECTED do phân loại sai.

Lưu ý: bạn chỉ có thể thực hiện phân loại tự động khi tạo mẫu.

Xét duyệt mẫu

Các mẫu có trạng thái PENDING sẽ trải qua quy trình xét duyệt mẫu. Chúng tôi sẽ xem xét nội dung của từng mẫu mới tạo hoặc đã chỉnh sửa để đảm bảo mẫu đó tuân thủ các chính sách và nguyên tắc về nội dung của chúng tôi. Tùy theo kết quả xét duyệt, chúng tôi sẽ tự động thay đổi trạng thái của mẫu thành APPROVED hoặc REJECTED. Hành động này sẽ kích hoạt webhook cập nhật trạng thái mẫu tin nhắn.

Trạng thái mẫu

Tùy theo kết quả xác thực hạng mục và xét duyệt mẫu, chúng tôi sẽ đặt hoặc thay đổi status của mẫu thành một trong các giá trị sau:

• APPROVED - Mẫu đã vượt qua quy trình xét duyệt mẫu và được phê duyệt. Giờ đây, bạn có thể gửi mẫu trong tin nhắn mẫu.
• PENDING - Mẫu đã vượt qua quy trình xác thực hạng mục và đang trải qua quy trình xét duyệt mẫu.
• REJECTED - Mẫu không vượt qua quy trình xác thực hạng mục hoặc xét duyệt mẫu. Bạn có thể yêu cầu trường rejected_reason trên mẫu để lấy nguyên nhân.

Hãy xem tài liệu tham khảo về điểm cuối Mẫu tin nhắn WhatsApp để biết tất cả trường và trạng thái có thể có.

Phản hồi

Khi thành công, API này sẽ trả về ID, trạng thái và hạng mục của mẫu mới tạo. Có thể xảy ra 3 trường hợp:

• Chúng tôi đồng ý với hạng mục mà bạn đã chỉ định và mẫu hiện đang trải qua quy trình xét duyệt mẫu (status là PENDING).
• Chúng tôi không đồng ý với hạng mục mà bạn đã chỉ định (status là REJECTED)
• Chúng tôi đã tự động phê duyệt mẫu (status là APPROVED). Trường hợp này chỉ áp dụng cho mẫu xác thực có nút mật khẩu một lần.

{
    "id": "<ID>",
    "status": "<STATUS>",
    "category": "<CATEGORY>"
}

Thuộc tính phản hồi

Yêu cầu mẫu

Dưới đây là một yêu cầu mẫu để tạo mẫu khuyến mãi theo mùa có các thành phần sau đây:

• một tiêu đề văn bản
• một nội dung văn bản
• một chân trang
• 2 nút trả lời nhanh

Hãy tham khảo phần Yêu cầu mẫu để xem thêm ví dụ.

curl 'https://graph.facebook.com/v19.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Phản hồi mẫu

{
    "id": "572279198452421",
    "status": "PENDING",
    "category": "MARKETING"
}

Gửi mẫu

Sử dụng API Đám mây hoặc API Tại chỗ để gửi mẫu trong tin nhắn mẫu.

Cách làm tốt nhất cho mẫu marketing

Nút Từ chối nhận tin nhắn marketing

Bạn nên thêm nút Trả lời nhanh vào các mẫu được phân loại là MARKETING để giúp khách hàng dễ dàng từ chối nhận tin nhắn marketing. Như vậy, khách hàng có thể chọn không nhận tin nhắn marketing của bạn mà không cần phải chặn doanh nghiệp bạn. Do đó, bạn có thể sẽ tăng được lượng tin nhắn nhanh hơn. Vui lòng tham khảo bài viết này để biết thêm chi tiết về lợi ích khi thêm nút từ chối nhận tin nhắn vào các mẫu marketing của bạn.

Lấy mẫu

Gửi yêu cầu GET đến điểm cuối Tài khoản WhatsApp Business > Mẫu tin nhắn để lấy danh sách mẫu thuộc sở hữu của một Tài khoản WhatsApp Business.

Cú pháp yêu cầu

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?fields=<FIELDS>
  &limit=<LIMIT>

Thông số chuỗi truy vấn

Yêu cầu mẫu

curl 'https://graph.facebook.com/v19.0/102290129340398/message_templates?fields=name,status&limit=3' \
-H 'Authorization: Bearer EAAJB...'

Phản hồi mẫu

{
  "data": [
    {
      "name": "seasonal_promotion_text_only",
      "status": "APPROVED",
      "id": "564750795574598"
    },
    {
      "name": "seasonal_promotion_video",
      "status": "PENDING",
      "id": "1252715608684590"
    },
    {
      "name": "seasonal_promotion_image_header",
      "status": "PENDING",
      "id": "1372429296936443"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/v19.0/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
  }
}

Yêu cầu mẫu (Mẫu bị từ chối)

Bạn chỉ có thể trả về các mẫu có giá trị trường cụ thể bằng cách thêm trường đó và giá trị mong muốn vào yêu cầu của mình. Ví dụ: thêm status=REJECTED để chỉ lấy các mẫu bị từ chối.

curl 'https://graph.facebook.com/v19.0/104996122399160/message_templates?fields=name,status&status=REJECTED' \
-H 'Authorization: Bearer EAAJB...'

Phản hồi mẫu

{
  "data": [
    {
      "name": "seasonal_promotion_text_only_v4",
      "status": "REJECTED",
      "id": "564750795574598"
    },
    {
      "name": "discount_qualifier",
      "status": "REJECTED",
      "id": "163917509772674"
    },
    {
      "name": "limited_time_offer_tuscan_getaway_2023",
      "status": "REJECTED",
      "id": "202389039167147"
    },
    {
      "name": "2023_mar_promo_2",
      "status": "REJECTED",
      "id": "1116034925734553"
    },
    {
      "name": "2023_mar_promo",
      "status": "REJECTED",
      "id": "952600926095321"
    }
  ]
}

Truy xuất vùng tên của mẫu

Bạn cần phải có vùng tên của mẫu tin nhắn thì mới gửi được tin nhắn bằng mẫu tin nhắn.

Để lấy vùng tên của mẫu, hãy gửi yêu cầu GET đến điểm cuối /{whatsapp-business-account-ID} và thêm trường message_template_namespace.

Yêu cầu mẫu

curl -i -X GET "https://graph.facebook.com/v19.0/{whatsapp-business-account-ID}
  ?fields=message_template_namespace
  &access_token={system-user-access-token}"

Khi thành công, hệ thống sẽ trả về một đối tượng JSON có ID tài khoản WhatsApp Business và vùng tên:

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

Chỉnh sửa mẫu

Gửi yêu cầu POST đến điểm cuối Mẫu tin nhắn WhatsApp để chỉnh sửa mẫu. Bạn cũng có thể tự mình chỉnh sửa mẫu bằng cách sử dụng bảng điều khiển Trình quản lý WhatsApp > Công cụ trong tài khoản > Mẫu tin nhắn.

Giới hạn

• Bạn chỉ có thể chỉnh sửa các mẫu có trạng thái APPROVED, REJECTED hoặc PAUSED.
• Bạn chỉ có thể chỉnh sửa category hoặc components của mẫu.
• Bạn không thể chỉnh sửa category của mẫu đã phê duyệt.
• Bạn có thể chỉnh sửa các mẫu đã phê duyệt tối đa 10 lần trong khoảng thời gian 30 ngày hoặc 1 lần trong khoảng thời gian 24 giờ. Bạn không bị giới hạn số lần chỉnh sửa đối với các mẫu bị từ chối hoặc bị tạm dừng.
• Sau khi chỉnh sửa một mẫu đã phê duyệt hoặc bị tạm dừng, mẫu đó sẽ tự động được phê duyệt trừ khi không vượt qua quy trình xét duyệt mẫu.

Cú pháp yêu cầu

POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>

Nội dung yêu cầu POST

{
  "category": "<CATEGORY>",
  "components": [<COMPONENTS>]
}

Thuộc tính

Yêu cầu mẫu (Chỉnh sửa thành phần)

Yêu cầu mẫu đối với văn bản nội dung mẫu chứa cả nội dung marketing và tiện ích để chỉ chứa nội dung marketing.

curl 'https://graph.facebook.com/v19.0/564750795574598' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubcribe from Promos"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Yêu cầu mẫu (Chỉ chỉnh sửa hạng mục)

Yêu cầu mẫu để thay đổi hạng mục mẫu từ UTILITY thành MARKETING.

curl 'https://graph.facebook.com/v19.0/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "category": "MARKETING"
}'

Phản hồi mẫu

Phản hồi mẫu sau khi thành công.

{
  "success": true
}

Xóa mẫu

Sử dụng điểm cuối Tài khoản WhatsApp Business > Mẫu tin nhắn để xóa mẫu theo tên hoặc ID.

Lưu ý

• Nếu bạn xóa một mẫu đã được gửi trong mẫu tin nhắn nhưng chưa đến người nhận (ví dụ: do điện thoại của khách hàng tắt), trạng thái của mẫu sẽ được đặt thành PENDING_DELETION và chúng tôi sẽ tìm cách gửi tin nhắn đó trong 30 ngày. Sau thời gian này, hệ thống sẽ báo lỗi "Không có cấu trúc" và khách hàng sẽ không nhận được tin nhắn đó.
• Bạn không thể dùng lại tên của mẫu được phê duyệt đã xóa trong 30 ngày.

Xóa theo tên

Xóa mẫu theo tên sẽ xóa tất cả mẫu khớp với tên đó (nghĩa là các mẫu có cùng tên nhưng khác ngôn ngữ cũng sẽ bị xóa).

Cú pháp yêu cầu

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>

Yêu cầu mẫu

curl -X DELETE 'https://graph.facebook.com/v16.0/102290129340398/message_templates?name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Phản hồi mẫu

{
  "success": true
}

Xóa theo ID

Để xóa mẫu theo ID, hãy thêm ID mẫu cùng với tên mẫu vào yêu cầu; chỉ mẫu có ID mẫu trùng khớp mới bị xóa.

Cú pháp yêu cầu

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?hsm_id=<HSM_ID>,
  &name=<NAME>

Yêu cầu mẫu

curl -X DELETE 'https://graph.facebook.com/v19.0/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Phản hồi mẫu

{
  "success": true
}

Tìm hiểu thêm

Bước tiếp theo

• Bắt đầu sử dụng API Đám mây để gửi tin nhắn