Sign in

v1

latestOpenAPI 3.0.02026-07-2491237338.9 KB
WhatsApp Templates

Create a template

Creates a WhatsApp template.

post/whatsapp/templates

Request body

wabaIdstring required

WhatsApp Business Account ID.

namestring required

Name of the template.

languagestring required

Language code of the template. See Supported Languages for all codes.

category'AUTHENTICATION' | 'MARKETING' | 'UTILITY' required

Category of WhatsApp templates.

  • AUTHENTICATION: Enable businesses to authenticate users with one-time passcodes, potentially at multiple steps in the login process (e.g., account verification, account recovery, integrity challenges).
  • MARKETING: Include promotions or offers, informational updates, or invitations for customers to respond / take action. Any conversation that does not qualify as utility or authentication is a marketing conversation.
  • UTILITY: Facilitate a specific, agreed-upon request or transaction or update to a customer about an ongoing transaction, including post-purchase notifications and recurring billing statements.
subCategory'ORDER_STATUS'

Subcategory of WhatsApp templates.

  • ORDER_STATUS: Order status template is categorized as UTILITY template and apart from name and language of choice, it has general template components such as BODY, FOOTER and additionally subcategory as ORDER_STATUS.
messageSendTtlSecondsinteger

If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message. By default, messages that use an authentication template have a default TTL of 10 minutes, and messages that use a utility or marketing template have a default TTL of 30 days. Set its value between 30 and 900 seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or 30 and 43200 seconds (i.e., 30 seconds to 12 hours) for utility templates, or 43200 and 2592000 seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to -1, which will set a custom TTL of 30 days for either type of template. We encourage you to set a time-to-live for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable. Authentication templates created before October 23, 2024, have a default TTL of 30 days.

ctaUrlLinkTrackingOptedOutboolean

Optional. Indicates if template button click tracking is disabled. Set to true to disable button click tracking on the template, or false to enable. You can disable button click tracking on an individual template by setting this field to true. Once disabled, button engagement/clicks will not be displayed in the WhatsApp Manager when viewing the template's insights. If not provided, this value defaults to false, which means button click tracking is enabled by default.

Example request

{
  "wabaId": "whatsapp-business-account-id",
  "name": "sample_whatsapp_template",
  "language": "en",
  "messageSendTtlSeconds": 600,
  "components": [
    {
      "buttons": [
        {
          "autofill_text": "Autofill",
          "package_name": "com.example.myapplication",
          "signature_hash": "K8a%2FAINcGX7",
          "flow_id": "1",
          "flow_action": "navigate",
          "navigate_screen": "WELCOME_SCREEN"
        }
      ],
      "code_expiration_minutes": 5,
      "limited_time_offer": {
        "text": "Expiring offer!"
      },
      "cards": [
        {
          "components": [
            {
              "buttons": [
                {
                  "autofill_text": "Autofill",
                  "package_name": "com.example.myapplication",
                  "signature_hash": "K8a%2FAINcGX7",
                  "flow_id": "1",
                  "flow_action": "navigate",
                  "navigate_screen": "WELCOME_SCREEN"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "ctaUrlLinkTrackingOptedOut": true
}

Response

Successfully created a WhatsApp template.

officialTemplateIdstring

Official template ID assigned by WhatsApp. This ID is used to identify the template in WhatsApp's system.

wabaIdstring required

WhatsApp Business Account ID.

namestring required

Name of the template.

languagestring required

Language code of the template. See Supported Languages for all codes.

category'AUTHENTICATION' | 'MARKETING' | 'UTILITY'

Category of WhatsApp templates.

  • AUTHENTICATION: Enable businesses to authenticate users with one-time passcodes, potentially at multiple steps in the login process (e.g., account verification, account recovery, integrity challenges).
  • MARKETING: Include promotions or offers, informational updates, or invitations for customers to respond / take action. Any conversation that does not qualify as utility or authentication is a marketing conversation.
  • UTILITY: Facilitate a specific, agreed-upon request or transaction or update to a customer about an ongoing transaction, including post-purchase notifications and recurring billing statements.
subCategory'ORDER_STATUS'

Subcategory of WhatsApp templates.

  • ORDER_STATUS: Order status template is categorized as UTILITY template and apart from name and language of choice, it has general template components such as BODY, FOOTER and additionally subcategory as ORDER_STATUS.
previousCategorystring

This field indicates the template's previous category (or null, for newly created templates after April 1, 2023). Compare this value to the template's category field value, which indicates the template's current category.

messageSendTtlSecondsinteger

If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message. By default, messages that use an authentication template have a default TTL of 10 minutes, and messages that use a utility or marketing template have a default TTL of 30 days. Set its value between 30 and 900 seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or 30 and 43200 seconds (i.e., 30 seconds to 12 hours) for utility templates, or 43200 and 2592000 seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to -1, which will set a custom TTL of 30 days for either type of template. We encourage you to set a time-to-live for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable. Authentication templates created before October 23, 2024, have a default TTL of 30 days.

status'PENDING' | 'REJECTED' | 'APPROVED' | 'PAUSED' | 'DISABLED' | 'ARCHIVED' | 'IN_APPEAL' | 'DELETED'

The status of a WhatsApp template.

  • PENDING: The template is still under review. Review can take up to 24 hours.
  • REJECTED: The template has been rejected during review process.
  • APPROVED: The template is approved, and you may begin sending it to customers.
  • PAUSED: The template has been paused due to recurring negative feedback from customers. Message templates with this status cannot be sent to customers. See Template Pausing.
  • DISABLED: The template has been disabled due to recurring negative feedback from customers or for violating one or more of our policies. Message templates with this status cannot be sent to customers. You may be able to edit a disabled message template and request an appeal. See Appeals.
  • ARCHIVED: The template has been archived. Archived templates cannot be sent or edited.
  • IN_APPEAL: The template is in appeal. See also Template Appeals.
  • DELETED: The template is deleted.
qualityRating'GREEN' | 'YELLOW' | 'RED' | 'UNKNOWN'

Quality rating of WhatsApp template. One of GREEN, YELLOW, RED, or UNKNOWN. See also Template Quality Rating.

  • GREEN: High quality.
  • YELLOW: Medium quality.
  • RED: Low quality.
  • UNKNOWN: Unknown quality.
reasonstring

The reason why the template is rejected.

createTimestring date-time

The time at which this object is created, formatted in RFC 3339. e.g., 2022-06-01T12:00:00.000Z.

updateTimestring date-time

The time at which this object is updated, formatted in RFC 3339. e.g., 2022-06-01T12:00:00.000Z.

statusUpdateEvent'PENDING' | 'APPROVED' | 'REJECTED' | 'IN_APPEAL' | 'PAUSED' | 'FLAGGED' | 'DISABLED' | 'ARCHIVED' | 'UNARCHIVED' | 'REINSTATED' | 'PENDING_DELETION'

Used when an event happened on WhatsApp template status updates.

  • PENDING: Pending.
  • APPROVED: Approved.
  • REJECTED: Rejected.
  • IN_APPEAL: In appeal. See also Template Appeals.
  • PAUSED: Paused. See also Template Pausing.
  • FLAGGED: Flagged. The template is scheduled for disabling.
  • DISABLED: Disabled. See also Template Pausing.
  • ARCHIVED: Archived. The template status is updated to ARCHIVED.
  • UNARCHIVED: Unarchived. The template status is restored to the current status returned by Meta. If the status is APPROVED, this event still does not represent a new approval review.
  • REINSTATED: Reinstated.
  • PENDING_DELETION: Pending deletion.
disableDatestring

The date at which the template will be disabled. When a WhatsApp template FLAGGED event is received, this field is set.

Example response

{
  "officialTemplateId": "official-template-id",
  "wabaId": "whatsapp-business-account-id",
  "language": "en_US",
  "messageSendTtlSeconds": 600,
  "components": [
    {
      "buttons": [
        {
          "autofill_text": "Autofill",
          "package_name": "com.example.myapplication",
          "signature_hash": "K8a%2FAINcGX7",
          "flow_id": "1",
          "flow_action": "navigate",
          "navigate_screen": "WELCOME_SCREEN"
        }
      ],
      "code_expiration_minutes": 5,
      "limited_time_offer": {
        "text": "Expiring offer!"
      },
      "cards": [
        {
          "components": [
            {
              "buttons": [
                {
                  "autofill_text": "Autofill",
                  "package_name": "com.example.myapplication",
                  "signature_hash": "K8a%2FAINcGX7",
                  "flow_id": "1",
                  "flow_action": "navigate",
                  "navigate_screen": "WELCOME_SCREEN"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "status": "REJECTED",
  "createTime": "2022-06-01T12:00:00.000Z",
  "updateTime": "2022-06-01T12:00:00.000Z",
  "disableDate": "December 9, 2022",
  "whatsappApiError": {
    "message": "HSM Template creation failed",
    "type": "OAuthException",
    "error_user_msg": "This message template cannot be created.",
    "error_user_title": "Message Cannot Be Submitted",
    "fbtrace_id": "AVGjJ7ia2zJkrHG"
  }
}