Pricing Changes (Deprecated)

    This document is deprecated and should only be used for reference purposes. All changes described here are now live. We have updated our existing Pricing document to reflect these changes.

    Launch Timeline

    To support the new pricing changes announced earlier this year on the WhatsApp Business Platform, the following changes were introduced on the dates indicated. For On-Premises API users, the changes described in this document were made available for v2.45 on June 1, 2023.

    Condensed timeline and summary

    February 2, 2023

    • New template categories are live in Graph API v16 and WhatsApp Manager; category selection is not validated as part of template review and approval until April 1 (templates can be approved with categories that don’t match our categorization prior to April 1).
    • WhatsApp Manager now only supports the new template categories.
    • New rate cards for utility, marketing published; Authentication rate card to be published ahead of June 1 launch.

    March 1, 2023

    March 17, 2023

    March 27, 2023

    April 1, 2023

    May 1, 2023

    May 5, 2023

    May 15, 2023

    May 29, 2023

    • All newly created authentication templates must include a one-time password button.

    June 1, 2023

    July 11, 2023

    • Parameter value restrictions now apply when sending authentication templates via On-Premises API.

    For reference, see our visual summary of the preparation required and key milestones.

    February 2, 2023

    New template categories

    Templates created or edited using v16.0 must now be categorized using one of the following categories; all other categories are no longer supported. Note that template categories will not factor into template review until April 1, 2023, and will not factor into conversation pricing until June 1, 2023.

    • AUTHENTICATION
    • MARKETING
    • UTILITY

    For example, use this syntax to create a template with the new UTILITY category:

    POST /v16.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>
  &category=UTILITY  // New category value, "UTILITY"
  &language=<LANGUAGE>
  &components=<COMPONENTS>

    See Template Category Guidelines to learn which categories to use with your templates.

    WhatsApp Manager

    Templates created or edited using the WhatsApp Manager can only use the new template categories listed above.

    New Rate Cards

    New rate cards for utility and marketing conversations are published. Authentication conversation rates will be released at a future date, prior to June 1, 2023, when all new rates go live.

    March 1, 2023

    Free entry point conversation window

    Free entry point conversations now generate a single, 72 hour conversation window.

    March 17, 2023

    New template category update webhook

    A new webhook subscription field, template_category_update, is now available. If subscribed to this field, anytime a template's category changes you will receive a webhook indicating the template's previous and new category.

    We will begin first template category migration on March 27, 2023 (2023-03-27T00:00:00 Pacific Daylight Time, UTC-O7:00), but migration results will not be available in the WhatsApp Manager until April 1, 2023. If you would like to be informed as soon as your templates have been migrated, subscribe to this new field before March 27, 2023.

    Sample webhook:

    {
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "106526625562206",
      "time": 1674864290,
      "changes": [
        {
          "field": "template_category_update",
          "value": {            
            "message_template_id": 1116034925734553,
            "message_template_name": "order_confirmation",
            "message_template_language": "en_US",
            "previous_category": "TRANSACTIONAL",
            "new_category": "UTILITY"
          }
        }
      ]
    }
  ]
}

    March 27, 2023

    First template category migration begins on March 27, 2023 (2023-03-27T00:00:00 Pacific Daylight Time, UTC-O7:00) with an expected completion date of April 1, 2023. Migration results will be available in the WhatsApp Manager on April 1, 2023, but you can be informed of your migration results immediately by subscribing to the new template_category_update field.

    To ensure you receive webhooks for each of your migrated templates, subscribe to this field before March 27, 2023.

    April 1, 2023

    Template category validation

    Template category validation is now part of the template review process for API v16.0 and the WhatsApp Manager.

    API Behavior

    API responses to template creation or editing requests now include the template's status and category. This applies to all API versions. For example:

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

    In addition, for v16.0+ requests, if we determine that a template has been miscategorized we will set its status to REJECTED and send you a template status webhook indicating that it was rejected for miscategorization.

    Note that you can include allow_category_change=true in your request to avoid template rejection due to miscategorization. Including this parameter and value tells us to assign a category based on our template guidelines and the template's contents. This can prevent your template from being rejected for miscategorization.

    If your template is rejected due to miscategorization, you have several options:

    • Edit the template using the WhatsApp Manager and use the category that it suggests.
    • Appeal the rejection and explain your categorization decision.
    • Edit the template so that it doesn't contain mixed content. For example, if the template contains a delivery update (which we categorize as utility) and a discount code (which we categorize as marketing), remove the marketing content and categorize the template as utility.
    • Edit the template using the WhatsApp Message Template endpoint and include the allow_category_change parameter set to true.

    Note that making these changes only affects category review. Your template could still be rejected for other reasons unrelated to its categorization.

    WhatsApp Manager Behavior

    The WhatsApp Manager will now validate a template's category as part of the creation or editing process and warn you if the submission will be rejected for miscategorization.

    Screenshot of category mismatch warning

    First template category migration

    We will assign all existing templates a new template category based on their content and our template guidelines. This process only affects a template's category. It has no effect on template status and will not factor into pricing until June 1, 2023.

    You can view migration results in the WhatsApp Manager > Account tools > Message templates panel by clicking the See all updates button in the Alerts banner.

    Screenshot of Message templates panel with alerts banner
    Screenshot of migration results window with recategorized templates highlighted

    You can also view migration results via the API by querying the WhatsApp Business Account > Message Templates endpoint and requesting the category field and the new previous_category field on returned templates. This field indicates what a template's category had been prior to the migration.

    Categorization appeals

    If you disagree with the category that we assigned a given template, you can use the migration results window to appeal the categorization until May 15, 2023. To appeal, while in the migration results window, select each template you wish to appeal, click the Edit category button, then complete the flow.

    Screenshot of migration results window with Edit Category button highlighted

    Note that categorization appeals submitted through WhatsApp Manager will not affect a template's status. If your template was already approved when you submitted an appeal, it will remain approved even if we reject your appeal (and it retains the category we assigned it).

    Free tier conversations

    Business-initiated conversations are no longer eligible for free tier conversations. If your WhatsApp Business Account relies on the services of a Solution Partner or a Meta partner, you are exempt from these changes until June 1, 2023.

    The first 1,000 user-initiated or service conversations each month will continue to be free. Also, messages sent from test phone numbers to test recipient phone numbers are still free. Test phone numbers and test recipient phone numbers are displayed in the WhatsApp > Getting started panel in the App Dashboard.

    New template rejection reason

    A new INCORRECT_CATEGORY rejection reason will be added that identifies templates that have been rejected due to miscategorization. This value will appear in template status webhooks.

    Templates rejected for miscategorization can also be identified in the WhatsApp Manager > Account tools > Message templates panel when clicking a rejected template. These templates will have an information banner stating:

    "This template contains content that does not match the category you selected. You can edit the template and re-submit for review. Or, if you believe this is correct, you can request a review in Account Quality."

    Template status webhooks

    Message template status webhooks now include a new INCORRECT_CATEGORY template rejection reason entry.changes.value.reason) to indicate if a given template has been rejected for miscategorization.

    {
  "entry": [
    {
      "id": "104996122399160",
      "time": 1673909279,
      "changes": [
        {
          "value": {
            "event": "REJECTED",
            "message_template_id": 685388923260781,
            "message_template_name": "2023_mar_promo_15_off",
            "message_template_language": "en_US",
            "reason": "INCORRECT_CATEGORY"
          },
          "field": "message_template_status_update
        }
      ]
    }
  ],
  "object": "whatsapp_business_account
}

    Template sample variables

    Templates created or edited using any API version or the WhatsApp Manager that have one or more variables will now require a sample in order to be submitted for review.

    Add samples using the API by including the example property in your components array.

    For example:

    [
  {
    "type":"BODY",
    "text":"Hi {{1}}, here is the temporary access code you requested: {{2}}",
    "example": {
    	"body_text": [
        [
          "Mark",
          "XNSS-HSJW"
        ]
      ]
    }
  }
]

    New message template node field

    A new WhatsApp Message Template node field, previous_category, will be available on all API versions. This field indicates the template's previous category (or null, for newly created templates). Compare this value to the template's category field value, which indicates the template's current category.

    When we complete template category migration, you can request the previous_category field using field expansion with the WhatsApp Business Account > Message Templates endpoint to get all of a WhatsApp Business Account's templates and their previous and current categories.

    Sample request:

    curl -X GET 'https://graph.facebook.com/v16.0/104996122399160/message_templates?fields=id,name,status,category,previous_category' \
-H 'Authorization: Bearer EAAJB...'

    Sample response:

    {
    "data": [
        {
            "id": "1365820850834232",
            "name": "access_code",
            "status": "APPROVED",
            "category": "AUTHENTICATION",
            "previous_category": "OTP",
        },
        {
            "id": "1123777071643310",
            "name": "2023_jan_promo_15_off",
            "status": "APPROVED",
            "category": "MARKETING",
            "previous_category": "MARKETING",
        },
        ...
    ],
    "paging": {
        "cursors": {
            "before": "MAZDZD",
            "after": "MjQZD"
        }
    }
}

    May 1, 2023

    New template categories required on all API versions

    Templates created or edited using any API versions must now be categorized using one of the new template categories, and template category validation is now part of template review for all API versions.

    Authentication templates with one-time password buttons available

    Authentication templates with one-time password (OTP) buttons are available to all businesses except businesses based in India. These templates make it easy for users to verify one-time passwords or verification codes that you have delivered to their WhatsApp phone numbers via our APIs. Users can either tap a button to copy delivered passwords or codes and paste them into your app, or tap a one-tap autofill button that automatically passes the password or code to your app.

    We recommend that you replace all of your existing authentication templates with authentication templates with OTP buttons before April 1, 2024. Legacy templates will no longer be usable after April 1, 2024.

    May 5, 2023

    Final template category migration

    We will perform template category migration again on any newly created templates that do not use the new template categories; i.e. any templates created using v15.0 or older on or after March 27, 2023 (2023-03-27T00:00:00 PDT, UTC-O7:00).

    May 15, 2023

    Template categorization appeal process closed

    You can no longer appeal the category we assigned your templates as part of the template category migration process.

    May 29, 2023

    All newly created authentication templates must include a one-time password button.

    June 1, 2023

    New conversation rates

    Conversation rates are now based on conversation categories. See the Pricing document for complete rate details and updated rate cards.

    The switch to the new pricing model will be performed June 1, 2023 at 12 AM, according to each WhatsApp Business Account's timezone setting. Conversations opened on or before this date and time will continue to use today's conversation rates and logic until they expire. Conversation windows opened after this date and time will use the new conversation-based pricing and logic.

    Free tier conversations

    Business-initiated conversations (now marketing, utility, and authentication) are no longer eligible for free tier conversations, only user-initiated conversations. This change now applies to all businesses.

    Multiple conversation windows

    It is now possible to have multiple billable conversation windows open with a given customer. See the Pricing document for an explanation of how conversation windows now work.

    Message status webhooks

    The category property of pricing objects in message status webhooks will now have one of the following values, which identifies the conversation category.

    • authentication — Indicates the business initiated the conversation with a message template categorized as AUTHENTICATION.
    • marketing — Indicates the business initiated the conversation with a message template categorized as MARKETING.
    • utility — Indicates the business initiated the conversation with a message template categorized as UTILITY.
    • service — Indicates the user initiated the conversation.
    • referral_conversion — Indicates the user initiated the conversation by clicking a Click to WhatsApp ad or a Facebook Page Call-to-Action button.

    These values are also repeated in the type property in the origin property (conversation.origin.type).

    For example, here's an example of a message status webhook for an authentication conversation:

    {
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "104996122399160",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLM...",
                "status": "delivered",
                "timestamp": "1674076968",
                "recipient_id": "15550051310",
                "conversation": {
                  "id": "91729e1df277b2ad74fc5fb6273eb3d1",
                  "origin": {
                    "type": "authentication"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "authentication" // Indicates conversation category
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

    The following category property values are no longer supported in message status webhooks:

    • business_initiated — Replaced with authentication, marketing, and utility.
    • user_initiated — Replaced with service.

    Conversation metrics

    The conversation_analytics field for getting WhatsApp Business Account metrics now supports a new optional conversation_categories filter and the dimensions filter now supports a new conversation_category argument. Use these together to filter results to only include metrics for conversations whose categories match any of the categories specified and break down results by conversation category.

    Supported conversation_categories filter arguments:

    • authentication
    • marketing
    • service
    • utility

    Supported dimensions filter arguments:

    • conversation_category (New)
    • conversation_direction
    • conversation_type
    • country
    • phone

    Specify categories as an array of strings. For example:

    conversation_categories(["utility", "marketing"])

    Specify dimensions as an array of strings. For example:

    dimensions(["conversation_type", "conversation_category"])

    Query syntax:

    GET /v16.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>
  ?fields=conversation_analytics
    .start(<START>)
    .end(<END>)
    .granularity(<GRANULARITY>)
    .conversation_categories([<CONVERSATION_CATEGORIES>])
    .dimensions([<DIMENSIONS>])

    Sample request:

    curl -X GET 'https://graph.facebook.com/v19.0/104996122399160/?fields=conversation_analytics.start(1672539163).end(1673748763).granularity(MONTHLY).conversation_categories(["utility","marketing"]).dimensions(["conversation_category"])' \
-H 'Authorization: Bearer EAAJB...'

    Sample response:

    {
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1673040600,
            "end": 1673042400,
            "conversation": 2,
            "conversation_category": "MARKETING",
            "cost": 0.039
          },
          {
            "start": 1673040600,
            "end": 1673042400,
            "conversation": 2,
            "conversation_category": "AUTHENTICATION",
            "cost": 0.035
          },
          {
            "start": 1673042400,
            "end": 1673044200,
            "conversation": 1,
            "conversation_category": "MARKETING",
            "cost": 0.039
          },
          {
            "start": 1673042400,
            "end": 1673044200,
            "conversation": 1,
            "conversation_category": "AUTHENTICATION",
            "cost": 0.035
          }
        ]
      }
    ]
  },
  "id": "104996122399160",
}

    Payload Value Restrictions

    Payload values included when sending authentication templates cannot exceed 15 characters, and URLs, media, and emojis are not supported.

    Legacy authentication templates which contain restricted content (media, links or emoji) can continue to be sent via our APIs until June 1. Legacy authentication templates which do not contain restricted content (media, links or emoji) can continue to be sent via our APIs until April 1, 2024, after which they can no longer be used.

    July 11, 2023

    Parameter Value Restrictions

    Parameter values included when sending templates categorized as AUTHENTICATION cannot exceed 15 characters, and URLs, media, and emojis are not supported.

    Applies to On-Premises API v2.49 and later, and all Cloud API versions.

    On-Premises API v2.45

    All of the changes described in this document are now available for use with On-Premises API v2.45.