Use Tab, then Enter to open a result.
WhatsApp Error 102 represents a validation failure. It indicates that the API request reaches the server but the template components do not align with the approved version in the Meta Business Manager. This failure stops message delivery immediately. For developers building SaaS automations, this error typically surfaces when implementing dynamic buttons like Call-to-Action (CTA) links or Quick Replies.
Fixing this error requires a precise mapping of the components array. Unlike standard text templates, button templates follow a strict indexing system. If the JSON payload specifies a button that does not exist in the template, or if it misses a required parameter for a dynamic URL, the system returns Error 102.
Understanding the Anatomy of Error 102
The 102 error code signals a mismatch. Meta requires that every variable defined in a template during the approval process has a corresponding value in the API call. If your template has two buttons and you only provide parameters for one, the request fails. If you provide parameters for a button that has no dynamic variables, the request also fails.
This error occurs most frequently with dynamic URLs. In these templates, a portion of the URL is static, and a variable suffix is appended at runtime. The API treats the button as a separate component that needs its own parameter object. Mapping these objects incorrectly causes the 102 validation error.
Prerequisites for Troubleshooting
Before adjusting your code, verify these items in your environment:
- Access to the Meta Business Manager or your WhatsApp Business Solution Provider (BSP) dashboard.
- The exact name of the template causing the failure.
- The specific language code used during template creation.
- A tool to inspect the approved template structure, such as the Graph API Explorer or a webhook logger.
If you use a service like WASenderApi to manage sessions, ensure your session is active and the template exists on the associated WhatsApp account. While WASenderApi operates via QR-linked sessions, template messaging through the official Cloud API remains the primary source for 102 error codes. Use the following steps to resolve the mismatch in your integration.
Step 1: Inspect the Approved Template Structure
You must know what Meta expects. Open your WhatsApp Manager and find the specific template. Check if the button is a Quick Reply or a CTA button. For CTA buttons, determine if the URL is static or dynamic. A dynamic URL contains a placeholder like {{1}} at the end of the link.
If the placeholder exists, the API expects a button component in the JSON payload. If the placeholder is missing, including a button parameter in your API call results in Error 102. The API sees the extra data as an invalid parameter for a static component.
Step 2: Construct the Correct JSON Payload
The payload structure for buttons is nested within the components array. Each button requires a type, sub_type, index, and a parameters array. The index is zero-based and refers to the position of the button in the template configuration.
Here is a valid JSON payload for a template with a dynamic URL button in the first position:
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "1234567890",
"type": "template",
"template": {
"name": "order_tracking_update",
"language": {
"code": "en_US"
},
"components": [
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [
{
"type": "text",
"text": "TRK123456"
}
]
}
]
}
}
In this example, the index is "0" because the tracking link is the first button. If you have multiple buttons, ensure the index values match their order in the template builder.
Step 3: Map Component Indexes and Sub-types
Developers often confuse sub_type values. Use url for CTA buttons and quick_reply for standard interaction buttons. If you use the wrong sub-type, the 102 error persists even if the text parameters are correct.
When a template includes both a header variable and a button variable, the components array must contain two separate objects. One object has the type header and the other has the type button. Failure to separate these or placing button parameters inside the header object triggers the 102 error.
Practical Example: Multi-Button Payloads
Consider a template with a dynamic header and two dynamic URL buttons. The first button links to a tracking page. The second button links to a support portal. The payload must explicitly define both button indexes.
{
"messaging_product": "whatsapp",
"to": "1234567890",
"type": "template",
"template": {
"name": "delivery_alert",
"language": {
"code": "en_US"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "text",
"text": "Customer Name"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [
{
"type": "text",
"text": "ORDER-99"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "1",
"parameters": [
{
"type": "text",
"text": "SUP-88"
}
]
}
]
}
}
Missing the second button object or providing the wrong index for the support link leads to an invalid component error. Each dynamic element requires its own entry in the array.
Debugging Dynamic URL Suffixes
A dynamic URL button in WhatsApp consists of a base URL and a single variable suffix. You cannot place the variable in the middle of the URL. It must appear at the end. For example, https://example.com/track/{{1}} is valid. https://example.com/{{1}}/track is invalid.
If your template was approved with an invalid variable placement, Error 102 often appears when you attempt to send it. In this case, delete the template and recreate it with the variable at the end of the URL string. Ensure the parameter you send in the API call contains only the suffix, not the full URL.
Edge Cases and Common Pitfalls
Character Limits and Encoding
Button parameters have character limits. Text parameters for buttons usually support up to 1024 characters. Exceeding this limit causes a validation failure. Additionally, ensure your variables do not contain line breaks or tabs. Buttons support plain text only. If your dynamic suffix includes special characters, use standard URL encoding to prevent the API from rejecting the payload.
Language Code Mismatch
Error 102 sometimes hides a language issue. If your template exists in en_US but you send the request with the en code, the API might not find the correct component structure. Use the exact language string displayed in your Meta dashboard.
White Space in Index Values
The index value must be a string representing an integer. Adding spaces or using a numeric type where the SDK expects a string leads to intermittent 102 errors depending on the library you use. Stick to strict string formatting: "0", "1", "2".
Troubleshooting Workflow
When a 102 error occurs in production, follow this sequence to isolate the cause:
- Log the Raw Request: Capture the exact JSON being sent to the WhatsApp API. Check for missing components.
- Verify Template State: Confirm the template is in the
APPROVEDstatus. Templates inPENDINGorREJECTEDstates cannot process dynamic parameters. - Test with Graph API Explorer: Paste your JSON into the Graph API Explorer. This tool often provides more detailed error messages than standard API responses.
- Check for Component Overlap: Ensure you are not sending
bodyparameters for a template that only hasbuttonparameters. The API rejects payloads containing variables for sections that do not have placeholders.
For developers using unofficial tools like WASenderApi for specific automation needs, remember that these tools often rely on the WhatsApp Web or Desktop protocol. If you encounter errors while using these alongside the Cloud API, check for session conflicts. Always maintain clear separation between your official API templates and your unofficial messaging flows to avoid confusing the validation logic.
FAQ
Why does my template work in the tester but fail in the API?
The WhatsApp Manager tester often fills in default values automatically. Your API call lacks these values. Compare the JSON structure used by the tester with your code to find missing component objects.
Can I have dynamic text in a Quick Reply button?
Yes. Quick Reply buttons support dynamic text if you defined them with a variable during creation. You must provide the payload or text parameter in the button component array using the correct index.
Does the order of the components array matter?
Yes. The API processes components in the order they appear in the template: Header, Body, Footer, then Buttons. While some parsers are flexible, maintaining this order reduces the risk of 102 errors.
What happens if I send too many parameters?
Sending more parameters than the template requires triggers Error 102. The API expects an exact match between the number of {{n}} placeholders and the number of items in your parameters array.
Can a 102 error be caused by an image header?
Yes. If your template has a media header and you fail to provide the image, video, or document object in the header component, the system returns a validation error. Ensure the type within the header object matches the media type of the template.
Conclusion and Next Steps
Resolving WhatsApp Error 102 requires a disciplined approach to JSON structure. Most failures stem from misaligned button indexes or missing component objects. By mapping each {{n}} placeholder to a specific entry in the components array, you ensure the API validates the request successfully.
To prevent these errors in the future, implement a validation layer in your application. This layer should check the template definition before sending the request. If the template requires a button parameter, the application must verify its existence in the outgoing payload. This proactive checking reduces delivery failures and improves the reliability of your SaaS messaging infrastructure. After fixing your button parameters, monitor your webhook delivery statuses to confirm that messages move from accepted to sent and delivered without further validation issues.
