WhatsApp API Usage Guide
This guide provides practical examples of using the Meta WhatsApp Business API with our service.
Table of Contents
Introduction
The WhatsApp Business API allows you to send template messages to your customers. Template messages are pre-approved message formats that can include text, media, and interactive components such as buttons.
To use this service, you'll need:
- A valid WhatsApp Business Account (WABA)
- Approved message templates
- Valid phone numbers registered with WhatsApp
- An API key from LlamadaPro
Template Messages
Template messages must follow Meta's approved format. These examples show how to construct valid template messages using our API.
Simple Text Template
A basic template with text variables in the body:
curl -X POST https://api.llamadapro.app/api/v1/messaging/whatsapp/messages/templates \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromPhoneNumber": "+1234567890",
"toPhoneNumber": "+0987654321",
"templateName": "welcome_message",
"languageCode": "en",
"variables": [
{ "value": "John" },
{ "value": "Doe" }
]
}'
Templates with Media
A template with an image in the header:
curl -X POST https://api.llamadapro.app/api/v1/messaging/whatsapp/messages/templates \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromPhoneNumber": "+1234567890",
"toPhoneNumber": "+0987654321",
"templateName": "product_update",
"languageCode": "en",
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"link": "https://example.com/product-image.jpg"
}
}
]
},
{
"type": "body",
"parameters": [
{ "type": "text", "text": "New Product" },
{ "type": "text", "text": "$99.99" }
]
}
]
}'
Templates with Buttons
Quick Reply Buttons
Quick reply buttons allow users to respond with predefined options:
curl -X POST https://api.llamadapro.app/api/v1/messaging/whatsapp/messages/templates \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromPhoneNumber": "+1234567890",
"toPhoneNumber": "+0987654321",
"templateName": "feedback_request",
"languageCode": "en",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "John" }
]
},
{
"type": "button",
"subType": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "FEEDBACK_YES"
}
]
},
{
"type": "button",
"subType": "quick_reply",
"index": "1",
"parameters": [
{
"type": "payload",
"payload": "FEEDBACK_NO"
}
]
}
]
}'
URL Buttons
URL buttons direct users to a website with a dynamic URL suffix:
curl -X POST https://api.llamadapro.app/api/v1/messaging/whatsapp/messages/templates \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromPhoneNumber": "+1234567890",
"toPhoneNumber": "+0987654321",
"templateName": "appointment_confirmation",
"languageCode": "en",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Dr. Smith" },
{ "type": "text", "text": "July 21, 2023" },
{ "type": "text", "text": "10:30 AM" }
]
},
{
"type": "button",
"subType": "url",
"index": "0",
"parameters": [
{
"type": "text", // Note: URL buttons use "text" type, not "payload"
"text": "abc123", // Dynamic URL suffix that will be appended to base URL defined in template
}
]
}
]
}'
Phone Number Buttons
Button that initiates a phone call:
curl -X POST https://api.llamadapro.app/api/v1/messaging/whatsapp/messages/templates \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromPhoneNumber": "+1234567890",
"toPhoneNumber": "+0987654321",
"templateName": "support_contact",
"languageCode": "en",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Customer Support" }
]
},
{
"type": "button",
"subType": "phone_number",
"index": "0",
"parameters": [
{
"type": "text",
"text": "+18001234567"
}
]
}
]
}'
Multi-Component Templates
Complex template with header, body, and multiple buttons:
curl -X POST https://api.llamadapro.app/api/v1/messaging/whatsapp/messages/templates \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromPhoneNumber": "+1234567890",
"toPhoneNumber": "+0987654321",
"templateName": "order_confirmation",
"languageCode": "en",
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"link": "https://example.com/order-image.jpg"
}
}
]
},
{
"type": "body",
"parameters": [
{ "type": "text", "text": "John Doe" },
{ "type": "text", "text": "Order #12345" },
{
"type": "currency",
"currency": {
"fallbackValue": "$99.99",
"code": "USD",
"amount1000": 99990 // $99.99 in thousandths
}
},
{
"type": "date_time",
"dateTime": {
"fallbackValue": "July 21, 2023"
}
}
]
},
{
"type": "button",
"subType": "url",
"index": "0",
"parameters": [
{
"type": "text",
"text": "order-12345" // Track order URL suffix
}
]
},
{
"type": "button",
"subType": "quick_reply",
"index": "1",
"parameters": [
{
"type": "payload",
"payload": "NEED_HELP_12345"
}
]
}
]
}'
Authentication Templates with OTP
Template with one-time password for authentication:
curl -X POST https://api.llamadapro.app/api/v1/messaging/whatsapp/messages/templates \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fromPhoneNumber": "+1234567890",
"toPhoneNumber": "+0987654321",
"templateName": "verification_code",
"languageCode": "en",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "MyApp" },
{ "type": "text", "text": "123456" }, // The OTP code
{ "type": "text", "text": "10" } // Minutes until expiration
]
},
{
"type": "button",
"subType": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "OTP_RECEIVED"
}
]
}
]
}'
Best Practices
-
Template Approval: All templates must be pre-approved by WhatsApp before use. Plan for 1-3 business days for approval (though approval often is quicker).
-
Variable Usage: Keep variable content neutral and within the context of the template to avoid rejections.
-
Button Format:
- Quick reply buttons use
type: "payload"in parameters - URL buttons use
type: "text"in parameters - Always use string values for
indexproperty (e.g., "0" not 0)
- Quick reply buttons use
-
24-Hour Window: After a user sends a message, you have a 24-hour window to respond with non-template messages.
-
Media Guidelines:
- Images: JPEG or PNG, max 5MB
- Videos: MP4, max 16MB
- Documents: PDF, max 100MB
-
Marketing Message Limits: Meta restricts the number of marketing template messages you can send to users who haven't responded to your previous messages. This helps prevent spam and encourages meaningful engagement.
Troubleshooting
Common Errors
| Error | Possible Solution |
|---|---|
| "Could not match union against any items" | Check button parameter types: URL buttons should use "type": "text", quick reply buttons should use "type": "payload" |
| "index is an excess property" | Make sure index is provided as a string value (e.g., "0" instead of 0) |
| "Template name does not exist" | Verify the template name exists and is approved for your WhatsApp Business Account |
| "Invalid parameter format" | Ensure all parameters match the expected format in your template |
Validation Errors
If you encounter validation errors:
- Check that the type names match exactly what's expected (case-sensitive)
- Verify that all required fields are provided
- Ensure that parameter types match the component type (e.g., URL buttons with text parameters)
- Confirm that the index values are provided as strings
- Check Meta's current documentation as format requirements may change
API Response Errors
If you receive an error from the WhatsApp API:
- Check request formatting according to Meta's current specifications
- Verify your credentials and access tokens
- Ensure your WhatsApp Business Account is in good standing
- Check for any rate limiting or temporary outages
- Review Meta's error codes documentation