How Templates Work
WhatsApp business-initiated messages must use a pre-approved template. This page explains template structure, components, and placeholders.
Template Structure
A template is a fixed message skeleton with {{1}}, {{2}} placeholders - only the dynamic values change per send.
A template has up to 4 components:
| Component | Purpose | Dynamic? |
|---|---|---|
| Header | Title at the top (text, image, video, or document) | Yes - text placeholders or media URL |
| Body | Main message content with {{1}}, {{2}}... | Yes - text values |
| Footer | Small text at the bottom (e.g. "Powered by Convoup") | No |
| Buttons | Call-to-action (URL suffix or quick reply) | Yes - URL path or reply text |
Example Template: test_welcome_template
template
Header: Welcome to {{1}}!
Body: Hi {{1}}, your account is ready. Your OTP is {{2}}.
Footer: Powered by Convoup
Buttons: [Visit Website] (dynamic URL: https://example.com/{{1}})In this example:
{{1}}in the header = company name{{1}}in the body = customer name (same position, different component){{2}}in the body = OTP code- Button URL suffix = dynamic path segment
How Placeholders Work
Placeholders are numbered starting from {{1}}. Each component has its own independent placeholder numbering:
{{1}}in the header is separate from{{1}}in the body- When you send the message, you provide values for each position in each component
- The SDK and REST API map your parameters to the correct placeholders
Creating Templates in Convoup
- Go to Templates in the Convoup dashboard
- Click Create Template
- Define your header, body, footer, and buttons
- Submit for Meta review
- Once approved, the template is available for sending
You never interact with Meta's template system directly - Convoup handles all Meta API compliance for you.
Template Approval Flow
graph LR
A[Create Template] --> B[Submit for Review]
B --> C{Meta Review}
C -->|Approved| D[Available for Sending]
C -->|Rejected| E[Fix & Resubmit]
E --> B
Template Categories
| Category | Use Case | Examples |
|---|---|---|
| TRANSACTIONAL | OTP, invoices, alerts, reminders | Login codes, billing notifications |
| MARKETING | Promotions, offers, product updates | Sale announcements, new features |
What Happens When You Send
- You provide a template name and parameter values
- The SDK builds a payload matching the template's component structure
- Convoup sends the request to the Meta WhatsApp Cloud API
- Meta validates the template exists and is approved
- Meta delivers the message to the recipient
If the template name is wrong or the parameter count doesn't match, the API returns an error before attempting delivery.
Next Steps
- SDK vs REST - When to use the SDK vs raw HTTP requests
- Template Discovery - Programmatically list templates and their parameters
- Sending OTPs - Your first send using a template