WhatsApp Media Template Pre-Approval API: An Automation Guide

What is WhatsApp Media Template Pre-Approval?

WhatsApp requires businesses to submit message templates for review before they send them to customers. This process ensures all content follows platform policies. A media template is a message that includes a header with an image, a video, or a document.

In a manual workflow, you upload these files through the Meta Business Suite interface. This works for a few templates. If you manage dozens or hundreds of templates across different languages, manual work becomes a bottleneck. The WhatsApp Media Template Pre-Approval API allows you to automate this submission process. You send your media and template details to Meta via code. Their system reviews the content and notifies you of the status.

Why Manual Template Management Fails at Scale

Manual uploads lead to human error. A team member might upload a file with the wrong aspect ratio or a file size that exceeds limits. These errors lead to immediate rejections. Correcting them manually takes more time.

Scaling operations requires a predictable system. When you use the API, you build validation rules into your software. Your system checks the file size and type before sending it to Meta. Automation also enables version control. You track when a template was submitted and who requested the change. This creates a clear audit trail for your communication strategy.

Prerequisites for API Integration

Before you write your first request, you need several components from the Meta developer ecosystem.

1. Meta Developer Account: Register as a developer on the Meta portal.
2. WhatsApp Business Account (WABA) ID: Locate this ID in your Business Settings under the WhatsApp Accounts tab.
3. System User Access Token: Create a system user in your Meta Business Suite. Generate an access token with whatsapp_business_management and whatsapp_business_messaging permissions.
4. Verified Business: Your business must complete the verification process to send high volumes of messages.

Step 1: Uploading Media for Template Headers

Unlike standard messaging, template creation requires you to upload the media file to Meta's servers first. This generates a media handle. You include this handle in your template creation request. Meta uses a resumable upload process for this task.

First, start the upload session to get an upload ID. You define the file size and the type of media.

curl -X POST "https://graph.facebook.com/v21.0/app_id/uploads" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d "file_length=150000" \
     -d "file_type=image/jpeg"

This request returns an upload ID. Next, upload the binary data of your file using that ID. This step requires the file content in the request body. Once finished, the API provides a handle string. This handle is a temporary pointer to your file. It remains valid for 30 days. Use it immediately to create your template.

Step 2: Structuring the Template Creation Request

With your media handle ready, you send a POST request to the message_templates endpoint. This endpoint resides under your WABA ID. The request body must follow a specific JSON structure.

You must define the category of the template. Meta uses three categories: Marketing, Utility, and Authentication. Choose Marketing for promotions or newsletters. Choose Utility for updates about existing transactions.

The JSON Payload Structure

Look at this example for a Marketing template with an image header. It includes a body and a call-to-action button.

{
  "name": "seasonal_sale_announcement",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": ["4p0rt_h4ndl3_v4lu3"]
      }
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}, our summer sale starts today! Get 20% off with code SUMMER20.",
      "example": {
        "body_text": [["John"]]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Shop Now",
          "url": "https://example.com/sale"
        }
      ]
    }
  ]
}

Notice the example fields. Meta requires these for the approval process. They provide context to the human or automated reviewer. Without examples, Meta rejects the template for lack of clarity.

Step 3: Implementing the Automation in Node.js

The following script demonstrates how to send the template creation request using the Axios library. It assumes you already have your media handle.

const axios = require('axios');

const WABA_ID = 'your_waba_id';
const ACCESS_TOKEN = 'your_access_token';
const API_VERSION = 'v21.0';

async function createMediaTemplate(mediaHandle) {
  const url = `https://graph.facebook.com/${API_VERSION}/${WABA_ID}/message_templates`;

  const payload = {
    name: 'order_delivery_update_v1',
    language: 'en_US',
    category: 'UTILITY',
    components: [
      {
        type: 'HEADER',
        format: 'DOCUMENT',
        example: {
          header_handle: [mediaHandle]
        }
      },
      {
        type: 'BODY',
        text: 'Your order {{1}} is out for delivery.',
        example: {
          body_text: [['#12345']]
        }
      }
    ]
  };

  try {
    const response = await axios.post(url, payload, {
      headers: {
        'Authorization': `Bearer ${ACCESS_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    console.log('Template submitted successfully:', response.data);
  } catch (error) {
    console.error('Error submitting template:', error.response.data);
  }
}

createMediaTemplate('your_media_handle_here');

This script handles the submission. After the request, the template enters a PENDING status.

Monitoring Approval Status via Webhooks

You do not need to poll the API to check for approval. Meta sends updates through webhooks. Configure your webhook listener to receive message_template_status_update events.

When Meta approves the template, the status changes to APPROVED. If they reject it, the status becomes REJECTED. The webhook payload includes a reason for rejection. Common reasons include policy violations or formatting errors. Set up your system to log these events. This allows your team to react quickly to rejections.

Common Rejection Scenarios and Fixes

Template rejections often happen for simple reasons. Understanding these helps you build better validation.

Formatting and Language Issues

If the language code in your request does not match the content, Meta rejects it. If you submit a template in Spanish but use the en_US code, the reviewer flags it. Ensure your code logic maps languages correctly. Avoid using all capital letters in the body text. This looks like spam and triggers filters.

Media Quality and Relevance

For media templates, the header must be high quality. Avoid blurry images or videos with low resolution. The media must also relate directly to the text. A utility template about a bank statement should not include a promotional image of a beach. This mismatch leads to rejection for being misleading.

Variable Mismatch

Ensure the number of placeholders in your body text matches the examples you provide. If you have {{1}} and {{2}} in your text, your body_text example array must contain two items. Missing placeholders cause technical rejections before a reviewer even sees the template.

Practical Use Cases for Automated Pre-Approval

Automation shines when your business needs dynamic content. For example, a logistics company creates a new template for every major holiday. Instead of a developer manually uploading these in December, a script generates them in November.

E-commerce platforms use this for personalized catalogs. If you want to send a document showing personalized recommendations, you need an approved document template. By automating the approval of the base template, you ensure your infrastructure is ready for high-volume delivery.

Official API vs Unofficial Alternatives

The Meta Business Management API is the formal way to handle templates. It provides the highest level of stability. Some developers use unofficial tools like WASenderApi for specific needs. WASenderApi allows for messaging via a standard WhatsApp session. This often removes the need for template approval because it simulates a mobile phone user.

This path offers more flexibility for message content. It carries risks regarding account suspension if used for high-volume cold outreach. For businesses that require the official Green Tick or high-volume reliability, the Meta API remains the standard choice. You can use both tools together. Use the official API for critical customer notifications and unofficial tools for internal experiments or flexible prototyping.

Troubleshooting Integration Errors

If your API calls fail, check the error codes.

• Error 100: This usually means a parameter is missing or formatted incorrectly. Double-check your JSON structure against the Meta documentation.
• Error 190: Your access token is expired or invalid. Refresh your system user token.
• Error 368: You reached a rate limit. Meta limits template creation to prevent spam. Reduce the frequency of your requests.

Check the permissions of your system user. If the user lacks the whatsapp_business_management permission, the API returns a 403 Forbidden error. Ensure the user is assigned to the WABA in the Business Settings.

FAQ

How long does it take for a template to be approved? Most templates are reviewed within minutes. Some take up to 24 hours. Automation does not speed up Meta's internal review time, but it reduces the time spent on the submission itself.

Can I edit a template after it is approved? Yes. You can edit an approved template. This triggers a new review process. During this time, you can still send the old version of the template until Meta approves the new one.

What are the file size limits for media headers? Images should be under 5MB. Videos and documents should be under 100MB. Keep files small to ensure fast delivery to customers with poor internet connections.

Is there a limit to how many templates I can have? Yes. Most WABAs start with a limit of 250 templates. You can request a limit increase through Meta support if your business needs more.

Does every language need a separate template? No. You create one template name and add multiple language translations under that same name. This keeps your template management organized.

Next Steps for Your Integration

Start by building a script that uploads a single image and creates a template. Once that works, integrate your webhook listener. This creates a full loop from submission to approval notification.

After you master the API, focus on data validation. Create a function that checks image dimensions and file sizes before the upload begins. This prevents unnecessary API calls and keeps your approval rate high. You are now ready to scale your WhatsApp communication with a robust, automated system.