WhatsApp templates and Business API
WhatsApp requires that business messages work with rules, pre-approved templates for the first message, a 24-hour window for free-form messages, and limits on attachments. This is how it works in Tesoro via Twilio.
When is this relevant?
Section titled “When is this relevant?”- First message to a contact fails, you are looking for the template rule
- The 24-hour window has expired and you don’t understand why you can no longer send
- You want to know what it costs
How the integration works
Section titled “How the integration works”Tesoro does not communicate directly with WhatsApp:
- Tesoro → message to Twilio API
- Twilio → forward to WhatsApp Business API (
whatsapp:prefix) - WhatsApp → delivery to recipient
- Status updates (delivered, read, failed) back via Twilio webhooks
- Incoming messages → real-time to all team members
What you need
Section titled “What you need”| Component | What |
|---|---|
| Twilio account | Active, with credit |
| WhatsApp Business profile | Approved by Meta via Twilio |
| Registered WhatsApp number | Specific for WhatsApp Business API; set in Settings → My Company → Call Settings |
| Twilio SID + Token | API credentials, configured by system administrator |
Message templates: what and why
Section titled “Message templates: what and why”Pre-approved message formats. Mandatory for the first message to a contact.
In Tesoro, each template has:
| Field | What | Validation |
|---|---|---|
| Title | Name to recognize | 3, 100 characters |
| Description | The content that is sent | 3, 100 characters |
Viewing templates
Section titled “Viewing templates”Auto-loaded when you open the WhatsApp tab on a record. Available for Admin and Employee.
Sending a template
Section titled “Sending a template”- WhatsApp tab of contact/deal/lead/relation.
- No conversation history? → system asks template selection.
- Choose from dropdown (title visible).
- Get Started → description is sent as message text.
- Message logged with delivery status, Twilio SID, and direction.
Approval process (Meta)
Section titled “Approval process (Meta)”- Create template: in Twilio or Meta Business Manager. Text + category (marketing, transactional, authentication) + variables.
- Review by Meta: minutes to days.
- Approval/rejection: Twilio dashboard or Meta Business Manager shows status.
- Registration in Tesoro: approved templates appear in dropdown.
Common reasons for rejection
Section titled “Common reasons for rejection”| Reason | Explanation |
|---|---|
| Misleading content | Inaccurate or misleading info |
| No opt-out | No unsubscribe option for recipient |
| Prohibited content | Gambling, alcohol, etc. |
| Incorrect formatting | Variables or formatting do not meet technical requirements |
Free-form messages vs templates
Section titled “Free-form messages vs templates”- When: first message or after expired 24-hour window
- How: select template, system sends description
- Attachments: not supported
- When: within 24-hour window after contact reply
- How: type whatever you want, max 1,600 characters
- Attachments: up to 10 files, max 1.5 MB each
Comparison:
| Feature | Template | Free-form |
|---|---|---|
| First message | ✅ mandatory | ❌ |
| Content | Predefined | Free |
| Max length | 100 characters (template limit) | 1,600 characters |
| File attachments | ❌ | ✅ (up to 10) |
| Approval required | ✅ (Meta) | ❌ |
The 24-hour conversation window
Section titled “The 24-hour conversation window”WhatsApp rule to prevent spam.
- You send template message → conversation opened.
- Contact replies → 24-hour window starts.
- 24 hours long → you can send free-form messages without template.
- No reply within 24h → window closes. New template needed to reopen conversation.
What to do when window expires
Section titled “What to do when window expires”Trying to send free-form message after 24 hours? WhatsApp rejects.
- Go back to template selection.
- Choose approved template.
- Send, window reopens.
- Wait for reply for free-form messages.
Media messages: sending files
Section titled “Media messages: sending files”Only with free-form messages, not with templates.
How Tesoro processes it:
- Each file = separate WhatsApp message via Twilio with
mediaUrl - Text = separate message
- Files stored in Tesoro + linked to message record
Supported types
Section titled “Supported types”| Type | Examples |
|---|---|
| Documents | PDF, Word, Excel |
| Images | JPEG, PNG, GIF, WebP |
| Audio | MP3, OGG |
| Video | MP4 |
| Archives | ZIP, RAR |
Limits: max 10 files per message, 1.5 MB each.
Receiving files
Section titled “Receiving files”Contact sends file → Tesoro:
- Detects via Twilio
NumMediawebhook - Downloads from Twilio media URL
- Saves in Tesoro with correct extension (from MIME type)
- Links to message record + contact
Delivery status and real-time updates
Section titled “Delivery status and real-time updates”Statuses
Section titled “Statuses”| Status | What |
|---|---|
| queued | In queue at Twilio |
| sent | Sent to WhatsApp |
| delivered | On recipient device |
| read | Recipient has read |
| failed | Not delivered |
Real-time updates
Section titled “Real-time updates”- Incoming message → notification to all users
- Status change → live update in chat view (no page refresh)
| Component | Explanation |
|---|---|
| Twilio message rate | Per message (in + out), varies by country |
| WhatsApp conversation rate | Per 24-hour window, difference between business-initiated (template) and user-initiated (reply) |
| Template category | Marketing > transactional > authentication |
| Media messages | Additional costs depending on type + size |
Permissions
Section titled “Permissions”| Action | Who |
|---|---|
| Send messages (free-form) | Admin, Employee |
| Send messages (template) | Admin, Employee |
| Read messages | Admin, Employee |
| View templates | Admin, Employee |
Common errors
Section titled “Common errors”- Template does not appear: check title + description (both 3, 100 characters). Possibly not registered in Twilio.
- “The selected template doesn’t match our records”: template ID no longer exists (deleted?).
- Message rejected after 24 hours: window expired. Send new template.
- Attachments not possible with template: use free-form message (after contact reply).
- “Company with Twilio WhatsApp number attached not found”: number in Twilio webhook does not match any company. Check Settings → My Company → Call Settings.
Next steps
Section titled “Next steps”WhatsApp and SMS basicsHow to send + receive and what setup is needed.
Phone callsPlan + call via Twilio.