WhatsApp mandates the use of pre-approved message templates to initiate conversations with your customers. This article will explain how to achieve this through our platform.
The template design page on BusinessChat is divided into three sections: The Template Management Section, the Template Content Section, and the Template Actions Section.
How to Create a New WhatsApp Template on BusinessChat
Important Note: You must always create WhatsApp templates through the BusinessChat platform. Avoid creating templates from the Facebook/Meta platform, as these templates may not appear on the BusinessChat platform.
To create a new WhatsApp template, follow these steps:
Click on your account Avatar icon on the BusinessChat platform (the icon at the bottom of the page), then click on Account Settings, and then click on the WhatsApp Message Templates page. Click the Create New Template button.
Click Create New Template from the pop-up window, or select a previous model to edit.
Add the Template Management Information:
Select how you intend to use your templates. (Usage)The template type must match the purpose or goal for which it is used. For example, if you intend to use it in an Abandoned Cart automation, select "Abandoned Cart" as the usage type. Note that if you selected a pre-existing model, this field will be unchangeable.
Add Template Name: The name is used to reference the template and must be in English, regardless of the template's language.
Select Language: This is the language of the template message.
Category: Meta will automatically determine the category based on the usage you selected.
Select Template Header: Text, Image, Video, or File. The header cannot combine more than one content type (e.g., it cannot be both text and image).
Important: After selecting the header, you will not be able to upload the image, file, or video directly; you can do this in the second step of creating the template.
Write the Template Text: This can contain variable text (placeholders) as needed, and emojis.
Template Footer: Mandatory and added automatically for all Marketing templates. It is optional for other uses. The footer box appears smaller with lighter text below the main text box.
Add Call-to-Action Buttons: You can choose between Call-to-Action buttons or Quick Reply buttons. Quick Replies allows you to assign a specific chatbot or pre-defined answers that are sent automatically when the customer clicks on one of the Quick Reply buttons. Whereas a CTA button sends the user to a website or allow them to make a call.
You can have up to two Call-to-Action buttons (Phone Call or Website Link).
You can add up to three Quick Reply buttons.
You cannot have more than one button of each Call-to-Action type (e.g., you cannot have two buttons linking to a website).
Buttons cannot include emojis.
Button text length is up to 35 characters.
You cannot combine Quick Reply buttons and Call-to-Action buttons.
After filling in all this data, click Next Step.
Review & Submit: In this step, you will need to provide examples to WhatsApp regarding the media and custom text (variables) you used in the template.
Add the Fallback Value for each variable text in the template (the value sent to users if the specific field data cannot be found). Then add the sample image or video in the header, and click "Submit Template".
Important Notes
Visibility: If the template does not appear when you try to use it, ensure it has been approved and that the "Usage" type you selected is appropriate. For example, Abandoned Cart templates will not be visible if you try to send them from the Inbox, and Customer Service templates will not appear in Bulk Marketing Campaigns.
Red Error Indicator: If you want to send a Customer Service template to open a closed conversation after 24 hours, but the message does not reach the customer, and a red error indicator appears below the message, Meta has likely determined the template category as "Marketing." To prevent disturbing the customer, Meta will not allow more than one marketing template per day. The category may differ from the usage you selected because it is determined automatically by Meta based on the template content.
Media Uploads: You cannot upload an image, file, or video in the first stage of template creation. You can only select the header type. In the second step, you can add a sample image, file, or video. Later, when using the template (e.g., in a bulk marketing campaign), you will be asked to upload the image, file, or video again.
Note: You cannot change the template message text after it has been approved.
Understanding WhatsApp templates Pricing
Meta costs for WhatsApp API message templates are based on the conversation categories or the template type.
How conversations Pricing Works
Meta/WhatsApp charges companies per conversation, based on the conversation category and the customer's country code.
A "conversation" is defined as a 24-hour session, regardless of the number of individual messages exchanged between the customer and the business during that period.
WhatsApp Conversation Categories
Business conversations are classified into four distinct intent types:
1. Customer Service Conversations
These are user-initiated conversations, typically involving general inquiries or support requests coming directly from customers.
2. Utility Conversations
These are business-initiated conversations used to notify customers about specific, agreed-upon transactions.
Use Cases: Order status notifications, delivery tracking, and Cash on delivery confirmation.
3. Authentication Conversations
These are business-initiated conversations used to verify user identity via One-Time Passcodes (OTP).
Use Cases: Account verification, account recovery, or identity confirmation.
4. Marketing Conversations
These are business-initiated conversations designed to drive sales or engagement. Any conversation that does not fall into Service, Utility, or Authentication is automatically classified as Marketing.
Use Cases: Promotions, discounts, abandoned cart reminders, Black Friday offers, new product launches, price updates, and satisfaction surveys.
Free Entry Point Conversations
For conversations initiated through Ads that click to WhatsApp or a Facebook Page Call-to-Action button:
The business has a 72-hour window to communicate with the customer free of charge. This is the only exception to the 24 hours window rule and applies only whent he conversation is initiated through a free entry point (ads that click to whatsapp, social media whatsapp buttons)
Important Requirements
Businesses cannot start a new conversation without a pre-approved Message Template.
The template must be assigned to the correct category corresponding to its content.
WhatsApp Business API Pricing Structure
Meta’s pricing structure is divided into three main categories, each with specific behaviors and cost implications:
1. User-Initiated Messages
If the customer begins the conversation:
The business can reply with Free-form messages (any message that is not a template) or Utility Templates for free within the 24-hour Customer Service window.
Exception: If a Marketing Template is sent within this window (even if the user started the chat), the cost will be charged based on the template type.
Example: Marketing Template cost: 0.17 SAR.
2. Business-Initiated Messages
If the business starts the conversation by sending a template:
This is considered "Business-Initiated," and costs apply immediately.
Pricing depends on the specific template category sent (e.g., Utility or Marketing).Marketing templates are always paid. Utility templates are free only when sent within an active 24-hour service window; otherwise, they incur a fee.
Each type is charged separately. Note that the standard free 24-hour service window does not apply to open the conversation; you pay to initiate it.
Marketing templates cost 0.17 SAR, while Utility templates cost 0.04 SAR.
3. Free Entry Point Conversations
If a user starts a conversation via a "Click-to-WhatsApp" Ad or a Facebook Page CTA button:
If the business replies within 24 hours, a free 72-hour window is activated.
During this 72-hour period:
You can send templates (Utility or Marketing) at no cost.
The standard 24-hour customer service window logic still applies within this period, meaning free-form replies continue to be free.
How to Open a Conversation When being Closed After 24 Hours ?
If you want to open a closed conversation with a customer, you must use a Customer Service template. Ensure it has been approved as a Service template and not Marketing. If it is approved as Marketing, Meta has likely classified the content as promotional.
The Solution: Re-create a new template using the "Customer Service" usage, but use one of the Customer Service models provided by BusinessChat and do not change the content until Meta approves it as a Service template.
Custom Content: If you want to write your own content, try it. If approved as "Service," proceed. If approved as "Marketing," send a preliminary template from the models provided by BusinessChat to ensure the message arrives.
WhatsApp Message Template Statuses
You can find the status of your templates on the "WhatsApp Templates" page on the BusinessChat platform. Once sent, the template will be "Pending Review." The WhatsApp team typically reviews your template within 24 hours; if approved, you can use it immediately.
Status Definitions:
Approved: WhatsApp has approved the template, and you can start using it.
Invalid: WhatsApp has disabled the template, primarily because your customers flagged the template as spam. Therefore, avoid sending unwanted messages or messaging contacts who do not know your brand. You cannot use this template.
In Appeal: The template is under review by the WhatsApp team after you submitted an appeal request following a Rejected, Disabled, or Paused status.
Paused: The template has been paused due to repeated negative feedback from customers. You cannot send templates in this state. Pause durations are:
1st Warning: Paused for 3 hours.
2nd Warning: Paused for 6 hours.
3rd Warning: Status changes to Inactive.
Pending Review: The template is being reviewed by WhatsApp. You need to wait for the decision before using it.
Rejected: WhatsApp rejected the template due to a violation of WhatsApp policies.
Attention: If a template has an Invalid status, hover over the icon, and a tooltip with solution information will appear.
Editing WhatsApp Message Templates
Only certain components of WhatsApp templates can be edited: Images, Files, Variable Fields, and Call-to-Action button links.
To edit a template:
Open the WhatsApp Templates page from your account settings on BusinessChat.
Choose the template you want to edit, click the three dots next to it, and click Edit.
Make the desired changes and click Send Template to have it approved again.
Important: You cannot edit the text of the template message. If you want to edit the content, you must create a new template.
Verifying Template Approval & Syncing
After creating a template, Sync Numbers to update the template status. Ensure the template is approved by WhatsApp before using it.
Template Approval: The process may take moments or up to 24 hours.
Sync Numbers: This updates the latest information on your WhatsApp numbers, including template statuses as they appear in your Facebook Business account.
Steps to Sync Numbers:
Click on your Profile Picture.
Select Settings from the menu.
From the side menu, select WhatsApp Numbers.
Click the green "Sync Numbers" button to update the number data.
After the sync is complete, check the template status again.
Why Doesn't the Template Appear Despite Approval?
The template type must match the purpose or goal of its use. If the selected usage does not match the purpose, the template will not appear in the search list.
Example: If you want to use it to open a closed conversation, the Usage type must be Customer Service. If you selected "Abandoned Cart," the template will not appear in the Inbox.
Always ensure the template type matches the usage before trying to send it in marketing campaigns or the Inbox.
How to Open a Closed Conversation with a Customer?
According to Meta's policies, you can communicate with open messages within 24 hours of the customer contacting you. During this window, you can send unlimited open messages. Conversations close automatically after 24 hours from the customer's last contact.
To open a closed conversation or start a conversation with a new customer:
Create a Customer Service template following the creation steps.
Find the customer's conversation via phone number, order number, or name in the customer list.
Click the "Send Template" button.
Select the template you created and send it.
If the customer replies to your message, a new 24-hour window will open, during which you can send any message without using templates.
Now that you know how to handle templates and create them. You need to be aware of what issues you might face while creating templates and how to fix them.
1.0 Troubleshooting During Template Creation
The foundation of a successful template is a correct setup that complies with Meta's strict policies. Most delivery issues can be prevented by avoiding common pitfalls during the initial creation and approval process. This section covers the key checks and processes to ensure your templates get approved and are built for success from the start.
1.1 Common Template Rejection Pitfalls: A Pre-Submission Checklist
The following reasons might prevent you from submitting a new template and you would see a pop up informing you of an error occuring while trying to submit the template. Check the following potential reasons:
Pitfall | How to Avoid |
Variable Formatting (Adjacent Variables) | Verify that your template does not begin or end with a custom variable (e.g., {{1}}). Ensure that static text surrounds variables for context. Avoid placing variables directly next to each other (e.g., {{1}}{{2}}) without intervening text. |
Excessive Whitespace | Ensure the text body is clean and compact. Do not include unnecessary newlines, tabs, or many consecutive spaces. |
Language Mismatch | Ensure the language selected in the template settings matches the actual content of the message body (e.g., do not select "English" if the text is in Arabic). |
Excessive Emojis | Maintain a professional tone and avoid spam filters by limiting emoji usage. |
Duplicate Templates | Do not submit a template that is identical in content to an already approved template. |
Duplicate Name | The template's name must not be a duplicate of another existing template. Even if you delete the old template, you will not be able to use the same name for 30 days. |
Mismatched Media Specifications | Confirm that any media meets WhatsApp's technical requirements: Images (JPEG/PNG, max 5MB), Videos (MP4, max 16MB), and Files (PDF only, max 100MB). |
Button Configuration Errors | Adhere to button limits: Maximum of two "Call to Action" (CTA) buttons OR three "Quick Reply" buttons. You cannot mix types in the same template, and you cannot have two CTAs of the same action type (e.g., two website links). |
Empty fileds | Ensure that all fields are completed with the necessary ifnromation. If you have a missing field, you will not be able to submit the template and the next step button would be grayed out. |
2.0 Troubleshooting When Using Templates in Campaigns & Automations
An approved template's usability depends entirely on its context. A template designed for one purpose may not be available or function correctly in another. This section addresses common problems that arise when a template is used in automations, bulk campaigns, or for direct customer service, focusing on why a perfectly valid template might not appear or function as expected.
2.1 Common "In-Use" Problems and Solutions for template
The following table outlines frequent issues encountered when trying to use templates in automations or bulk marketing campaigns and provides actionable solutions.
Problem | Primary Cause | Solution |
Template is not visible for selection in an automation or campaign. | The template's designated "Usage" type does not match the feature's purpose. For example, a template with the "Abandoned Cart" usage type will not appear when sending a message from the Inbox, which requires a "Customer Service" usage type. | First, check if another approved template with the correct "Usage" type already exists. If not, create a new template with the correct usage type that matches the context (e.g., automation, customer service, marketing campaign). |
A bulk campaign fails to start or sends messages without media. | When launching a bulk campaign, the media file (image, video, or document) was not uploaded again during the campaign setup flow. The initial template creation only specifies the type of media; it does not permanently store the file with the template. | During the campaign creation process, ensure you explicitly upload the desired media file when prompted after selecting your template. |
3.0 Diagnosing and Resolving Individual Message Delivery Failures
When a template message fails to deliver, Meta's API provides a specific error code that reveals the reason for the failure. This section will guide you on how to find this code and use it to identify and fix the root cause of the delivery problem.
3.1 How to Find the message Delivery Error Code
Follow these simple steps to locate the error code for a failed message:
Open the conversation containing the message that failed to deliver.
Locate the red exclamation mark icon (!) that appears below the failed message and next to the text that says “Failed to deliver”.
Click on the icon. A small pop-up window will appear displaying the specific error code.
Copy this code and use the table below to find the corresponding solution.
3.2 Common Meta Error Codes and Solutions
This table details the most common delivery errors, their causes, and how to resolve them.
Error Code | Description | Possible Solution |
1 | API Unknown: Invalid request or possible server error. | Check the WhatsApp Business Platform Status page. If no outages, try again. |
2 | API Service: Temporary downtime or a server overload. | Try again after some time. |
4 | API Too Many Calls: The app has reached its API call rate limit. | Try again later. |
33 | Parameter value is not valid: The business phone number has been deleted. | Verify that the business phone number is correct. |
100 | Invalid parameter: Request included unsupported or misspelled parameters. | Sync the WhatsApp number to get the latest template status, and create a new template if the current one has an issue. |
100 | Invalid parameter: Message must be a template message. | Ensure you are sending a template message. |
368 | Temporarily blocked for policy violations: The WABA has been restricted or disabled for violating a platform policy. | See the Policy Enforcement document to learn how to resolve violations or contact the BusinessChat team. |
80007 | Rate limit issues: The WhatsApp Business Account has reached its rate limit. | You have reached the limit for daily sending. Try again later. |
130429 | Rate limit hit: Per-Second Rate Limit Reached | Reduce the frequency with which the app sends messages. Try again later. |
130472 | User's number is part of an experiment: Message was not sent as part of an experiment. | You will not be able to send marketing templates to those users. If they open a customer service window with your store, or you send a Utility template and they reply, you will be able to send marketing messages as long as the 24-hour window is open. |
130497 | Business account restricted from messaging users in this country: WABA is restricted from messaging users in certain countries. | Cannot send them messages. |
131000 | Something went wrong: Message failed to send due to an unknown error. | Try again. If the error persists, open a Direct Support ticket. |
131008 | Required parameter is missing: The request is missing a required parameter. | See the endpoint's reference to determine which parameters are required. |
131009 | Parameter value is not valid: One or more parameter values are invalid. | Check the template’s custom fields or create a new one. |
131016 | Service unavailable: A service is temporarily unavailable. | Check the WhatsApp Business Platform Status page and try again. |
131021 | Recipient cannot be sender: Sender and recipient phone numbers are the same. | Send a message to a phone number different from the sender's. |
131026 | Message Undeliverable: Recipient is not a WhatsApp number, hasn't accepted TOS, or uses an old app version. | Confirm the recipient can receive messages, has accepted the latest TOS, and has updated their app. |
131031 | The account has been locked: WABA restricted due to a policy violation or verification failure. | See the WhatsApp number for Health Status. |
131037 | WhatsApp provided number needs display name approval: Test number needs an approved display name. | Change the display name in your WhatsApp Business settings. |
131042 | Business eligibility payment issue: Error related to payment method, credit line, or suspended account. | Verify billing setup, credit line, and currency settings in Billing or pay outstanding Meta bills. |
131045 | Incorrect certificate: Message failed to send due to a phone number registration error. | Register the phone number before trying again. |
131047 | Re-engagement message: More than 24 hours have passed since the recipient last replied. | Send the recipient a template message instead. |
131048 | Spam rate limit hit: Your WhatsApp number has messaging restrictions due to a history of being marked as spam or you have exceeded your daily sending limit (tier limit). | Check your number's quality status and sending limits in the WhatsApp Manager. Reduce sending frequency until the quality improves. |
131049 | Meta chose not to deliver: Message blocked to maintain ecosystem health (too many marketing messages). | Wait at least 24 hours before resending. |
131050 | User has stopped receipt of marketing messages: The Recipient opted out of marketing messages from your business. | Do not retry sending messages to this user. |
131051 | Unsupported message type: You are trying to send an unsupported message type. | See documentation for supported message types before trying again. (https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#message-types) |
131052 | Media download error: Unable to download media sent by the user. | Ask the user to send the media file using a non-WhatsApp method. |
131053 | Media upload error: Unable to upload media (e.g., unsupported type). | Inspect media files/MIME types and confirm they are supported. |
131055 | Method not allowed: Only marketing template messages are supported. | Ensure you are sending marketing templates. |
131056 | (Business Account, Consumer Account) pair rate limit hit: Too many messages sent to the same recipient in a short time. | Wait and retry, or send to a different phone number. |
131057 | Account in maintenance mode: WABA is undergoing maintenance or upgrade. | Wait and try again later. |
132000 | Template Param Count Mismatch: Variable values in the request do not match the parameters defined in the template. | Ensure the request includes values for all parameters defined in the template. |
132001 | Template does not exist: Template not approved, or incorrect name/language locale. | Verify the template is approved, and the name/language is correct. |
132005 | Template Hydrated Text Too Long: Translated text is too long. | Check WhatsApp Manager to verify translation status. |
132007 | Template Format: Character Policy Violated: Content violates a WhatsApp policy. | Create a new template. |
132012 | Template Parameter Format Mismatch: Variable values formatted incorrectly. | Ensure values match the format specified in the template. |
132015 | Template is Paused: Template paused due to low quality. | Edit the template to improve quality, then retry once it's approved. |
132016 | Template is Disabled: Template permanently disabled due to repeated low quality. | Create a new template with different content. |
132069 | Flow is throttled: 10 messages have already been sent in the last hour using this flow. | Try again after a while. |
133000 | Incomplete Deregistration: Previous deregistration attempt failed. | Deregister the number again before registering. |
133004 | Server Temporarily Unavailable: Server is temporarily unavailable. | Check the Platform Status page before trying again. |
133005 | Two-step verification PIN Mismatch: PIN incorrect. | Verify PIN. To reset, disable two-step verification and set a new PIN. |
133006 | Phone number re-verification needed: The Number needs verification before registering. | Verify and register the phone number. |
133008 | Too Many Two-Step Verification PIN Guesses: Too many attempts. | Try again after the time specified in the details response. |
133009 | Two-step verification PIN Guessed Too Fast: PIN entered too quickly. | Check the details response before trying again. |
133010 | Phone number Not Registered: Number not registered on WhatsApp Business Platform. | Register the phone number before trying again. |
133015 | Please wait a few minutes before attempting to register: The Number was recently deleted. | Wait 5 minutes before re-trying the request. |
133016 | Account register deregister rate limit exceeded: Too many attempts in a short period. | Try again once the number is unblocked. |
134011 | Payments TOS not accepted: The Payments terms of service acceptance is pending. | Accept the WhatsApp Payments terms of service. |
134100 | Only marketing messages supported: You are only able to send marketing messages on this API. | Send only marketing messages. |
134101 | Your template is still syncing: The Syncing process can take up to 10 minutes. | Wait a few minutes and try again. |
134102 | Template unavailable for use: Check eligibility status or contact support. | Ensure you are onboarded or contact customer support. |
135000 | Generic user error: Unknown error with request parameters. | Try again later or contact support. |
200005 | Template insights unavailable: Insights not available for this WABA yet. | You are unable to enable insights at this moment. |
2388001 | Please confirm ownership of this phone number. The certificate requires confirmed ownership. | Register and verify the number to download the certificate. |
2388019 | Message Template Limit Exceeded: You have exceeded the maximum number of templates (250). | A WABA can have up to 250 message templates. |
2388040 | Character limit exceeded: A field in your template exceeded the max limit. | Check the error message for specific details on field limits. |
2388047 | Message header format is incorrect: Header contains invalid formatting. | Refer to the error message for specific details. |
2388072 | Message body format is incorrect: Body contains invalid formatting. | Refer to the error message for specific details. |
2388073 | Message footer format is incorrect: Footer contains invalid formatting. | Refer to the error message for specific details. |
2388091 | Number not eligible to receive/verify registration: Phone ownership API unavailable for this use case. | Register and verify the number. |
2388103 | No payment account: WABA needs an active credit line. | Set up a credit line. |
2388293 | Parameters words ratio exceeds limit: Too many variables for message length. | Reduce the number of variables or increase the message length. |
2388299 | Leading or trailing parameters are not allowed: Variable at the start or end of thetemplate. | Refer to the error message for details. |
2494100 | Account is in maintenance mode: Number in maintenance mode. | Try again in a few minutes. |
NOTE: The same errors apply to templates sent in bulk campaigns, however, this method is specific to troubleshooting indivual message failure. If you have a failed bulk campaign, then it's better to troubleshoot the failure reasons from the campaign reports section.
Why customer service templates get categorized differently than intended?
The categorization process involves two steps: local selection by the business and validation by Meta.
Types of classification
User Selection: When you create a new template in BusinessChat, you must select the Intended Use (Usage) that matches your goal. For example, if you are creating a message to confirm an order, you should select "An order status template."
Meta Validation: Once you submit a template, Meta reviews the content. They determine the final category based on the text and media within the template.
2. Reasons for Misclassification of customer service templates as marketing isntead of utility
Misclassification usually occurs when Meta's automated review system detects that your message's content does not match the category you selected or intended.
Content vs. Intent Mismatch: If you select "Utility" or "Customer Service" but your message contains promotional language (e.g., "discount," "offer," or sales pitches), Meta will reclassify and approve it as Marketing.
Ambiguity: If the content is vague or could be interpreted as promotional, Meta defaults to classifying it as Marketing. These could include a simple message that shows you’re trying to contact a customer.
Why Misclassification of customer service templates as marketing isntead of utility is a Problem?
Delivery Failures: Meta limits the number of marketing messages a user can receive in a day. If you are trying to send a critical notification (like an order update) or re-open a support chat, but Meta has classified your template as "Marketing," the message may fail to deliver if the user has already reached their marketing message limit for the day.
Incorrect Pricing: Since pricing varies by category, a Utility message misclassified as Marketing may incur higher or different costs than anticipated.
Solutions to handle misclassified customer service templates
Solution 1: If a template meant for customer service/utility is approved as Marketing, you should create a new template with purely transactional/service language—removing any promotional keywords—and submit it again. Use the samples on the BusinessChat platform under the usage Agent response, if you are trying to create a customer service template and get it categorized as Utility by Meta.
Solution 2: If you need to write different content in your template other than the content of the samples, try to create a new template and see if it gets categorized as Utility. If you weren’t successful, we advise you to use a sample template to open the conversation first, since any Marketing template might get blocked from Meta, and then you will be able to write free-form messages to your customer once they reply.
Important note: This section is for customer service templates that get categorized as Marketing templates instead of Utility only. It doesn't mean that all templates should be categorized as Utility. Templates should be categorized based on their usage, for example all marketing automations should use Marketing templates, whereas Utility automations like COD and Order status should use Utility templates.