API Reference v1.0

WhatsApp Cloud API Features

A comprehensive overview of all WhatsApp Cloud API features available through WhatsBizAPI, including message types, template management, interactive messaging, conversation pricing, and quality controls.

1. Message Types Overview

WhatsBizAPI supports the full range of WhatsApp Cloud API message types. The table below summarises each type, its availability relative to the 24-hour service window, and key constraints.

Message Type	Window Required	Description	Key Limits
Text	Yes (24h)	Plain text with optional formatting (`bold`, `_italic_`, `~strike~`).	4,096 characters max
Template	No	Pre-approved message templates. The only way to initiate conversations outside the 24-hour window.	250 templates per WABA
Image	Yes (24h)	JPEG or PNG image with optional caption.	5 MB max
Video	Yes (24h)	MP4 video with optional caption.	16 MB max
Audio	Yes (24h)	AAC, MP3, OGG, or AMR audio file.	16 MB max
Document	Yes (24h)	PDF, DOC, XLS, PPT, or other document with optional filename and caption.	100 MB max
Sticker	Yes (24h)	Static (WebP) or animated sticker.	100 KB static / 500 KB animated
Reply Buttons	Yes (24h)	Interactive message with tappable quick-reply buttons.	Max 3 buttons, 20 chars each
List Message	Yes (24h)	Interactive message with expandable list sections and selectable rows.	Max 10 rows across all sections
Location	Yes (24h)	Share a geographic location with latitude, longitude, name, and address.	—
Contact Card	Yes (24h)	Share one or more contact cards with name, phone, email, and other fields.	—
Reaction	Yes (24h)	React to an existing message with a single emoji. Send an empty emoji to remove a reaction.	1 emoji per reaction

ℹ

Tip: Template messages are the only message type that can be sent outside the 24-hour customer service window. All other types require the customer to have messaged you first within the last 24 hours.

2. Template Management

Template Categories

Category	Purpose	Examples
MARKETING	Promotional content, offers, product announcements, and re-engagement.	Sale alerts, new product launches, abandoned cart reminders
UTILITY	Transactional updates related to an existing customer action or request.	Order confirmations, shipping updates, appointment reminders
AUTHENTICATION	One-time passwords and verification codes.	OTP delivery, two-factor authentication codes

Template Components

Each template is built from up to four components:

Component	Required	Description
HEADER	Optional	Supports `TEXT` (60 chars, 1 variable), `IMAGE`, `VIDEO`, or `DOCUMENT` format.
BODY	Required	Main message text (1,024 chars). Supports dynamic variables using `{{1}}`, `{{2}}`, etc.
FOOTER	Optional	Small text below the body (60 chars). No variables allowed.
BUTTONS	Optional	Up to 10 buttons of various types (see below).

Button Types

Button Type	Description	Max Count
Quick Reply	User taps to send a predefined reply. Returns a payload you can handle via webhook.	3
URL	Opens a URL in the user's browser. Supports one dynamic variable for personalised links.	2
Phone Number	Initiates a phone call to the specified number when tapped.	1
Copy Code	Copies a coupon code or OTP to the user's clipboard.	1

Approval Process

All templates must be reviewed and approved by Meta before they can be sent:

Status	Meaning
PENDING	Template has been submitted and is awaiting review (typically takes minutes to 24 hours).
APPROVED	Template passed review and can be used to send messages.
REJECTED	Template violated WhatsApp policies. Review the rejection reason, edit, and resubmit.

Quality Ratings

Meta assigns a quality rating to each template based on user feedback (blocks, reports):

Rating	Colour	Impact
High	GREEN	No restrictions. Template performs well.
Medium	YELLOW	Warning state. Improve content or targeting to avoid demotion.
Low	RED	Template may be paused or disabled. Immediate action required.

⚠

Template Limit: Each WhatsApp Business Account (WABA) can have a maximum of 250 message templates. Delete unused or low-quality templates to free up capacity.

3. Interactive Messages

Interactive messages provide structured ways for users to respond. They offer better engagement and easier processing compared to free-text replies.

ℹ

Window Required: Interactive messages (reply buttons and list messages) can only be sent within the 24-hour customer service window. Outside this window, use template messages with buttons instead.

Reply Buttons

Display up to 3 tappable buttons beneath your message. Each button has a unique id (returned via webhook when tapped) and a visible title.

Reply Button Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "919876543210",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {
      "type": "text",
      "text": "Order #12345"
    },
    "body": {
      "text": "Your order is ready. How would you like to proceed?"
    },
    "footer": {
      "text": "Tap a button to respond"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "btn_confirm",
            "title": "Confirm"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "btn_reschedule",
            "title": "Reschedule"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "btn_cancel",
            "title": "Cancel"
          }
        }
      ]
    }
  }
}

List Messages

Display a menu button that expands into categorised sections with selectable rows. Supports up to 10 rows total across all sections.

List Message Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "919876543210",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "body": {
      "text": "Browse our available services below."
    },
    "footer": {
      "text": "Select an option to learn more"
    },
    "action": {
      "button": "View Services",
      "sections": [
        {
          "title": "Consulting",
          "rows": [
            {
              "id": "svc_strategy",
              "title": "Strategy Session",
              "description": "1-hour strategy consultation"
            },
            {
              "id": "svc_audit",
              "title": "Business Audit",
              "description": "Full operational audit"
            }
          ]
        },
        {
          "title": "Support",
          "rows": [
            {
              "id": "svc_ticket",
              "title": "Open Ticket",
              "description": "Create a support request"
            },
            {
              "id": "svc_faq",
              "title": "FAQs",
              "description": "Browse frequently asked questions"
            }
          ]
        }
      ]
    }
  }
}

4. 24-Hour Messaging Window

WhatsApp enforces a customer service window to protect users from unsolicited messages. Understanding this window is essential for effective messaging.

Scenario	Window Duration	Allowed Message Types
Customer sends you a message	24 hours from last customer message	All types: text, media, interactive, templates
Outside the window (no recent customer message)	No active window	Template messages only
Click-to-WhatsApp ad or Facebook CTA	72 hours (free entry point)	All types — and the conversation is free of charge

⚠

Important: Attempting to send a free-form message (text, image, interactive, etc.) outside the 24-hour window will result in an API error. Always check the window status or fall back to a template message.

✓

Best Practice: Use a Click-to-WhatsApp ad to open a 72-hour free conversation window. During this period, all messages you send are free of charge, regardless of category.

5. Business Profile

Your WhatsApp Business Profile is visible to customers when they view your contact info. A complete, professional profile builds trust and improves engagement.

Field	Description	Limit
Profile Picture	Square image displayed as your business avatar.	640x640 px recommended
About	Short status text visible in the contact info header.	139 characters
Description	Detailed description of your business and services.	512 characters
Address	Physical business address.	256 characters
Email	Business contact email address.	128 characters
Website	Up to 2 website URLs.	256 characters each
Category	Business category (e.g., "Shopping & Retail", "Education").	Selected from Meta's predefined list

ℹ

Manage via Dashboard: You can update all business profile fields directly from the WhatsBizAPI dashboard under Settings → Business Profile. Changes may take a few minutes to propagate to users.

6. WhatsApp Flows

WhatsApp Flows allow you to build structured, multi-screen interactive experiences directly within the WhatsApp chat interface. Flows are ideal for collecting structured data without requiring users to leave the conversation.

Use Case	Description
Lead Generation	Multi-step forms to capture customer information (name, email, preferences).
Appointment Booking	Date/time selection screens with confirmation steps.
Surveys & Feedback	Structured questionnaires with multiple question types.
Customer Support	Guided troubleshooting flows with branching logic.
Product Selection	Browse and select products with quantity and variant options.

ℹ

Flow Management: WhatsApp Flows are created and managed via Meta Business Manager (business.facebook.com). Once published, flows can be triggered via template messages or interactive messages through the WhatsBizAPI.

7. Conversation Pricing

WhatsApp uses a per-message pricing model (effective post-July 2025). Costs vary by conversation category and the recipient's country.

Category	Approximate Cost	Notes
Marketing	$0.025 – $0.14 / msg	Country-dependent pricing. Promotional and re-engagement messages.
Utility	$0.004 – $0.05 / msg	Free when sent within the 24-hour customer service window.
Authentication	$0.004 – $0.05 / msg	Volume-based tiers available for high-volume senders.
Service	FREE	Customer-initiated conversations. No charge for responses within 24h window.

✓

Free Tier: Every WABA receives 1,000 free service conversations per month. These are customer-initiated conversations where the customer messages you first.

ℹ

Free Entry Points: Conversations originating from Click-to-WhatsApp ads or Facebook Page CTAs are entirely free for 72 hours, regardless of message category.

8. Quality Rating & Messaging Limits

WhatsApp assigns a messaging limit tier to each phone number based on verification status and quality history. Higher tiers allow you to reach more unique customers in a rolling 24-hour period.

Messaging Limit Tiers

Tier	Unique Customers / 24h	Requirement
Unverified	250	Default for unverified business phone numbers.
Tier 1	1,000	Complete business verification.
Tier 2	10,000	Use 50%+ of Tier 1 limit within 7 days with GREEN quality.
Tier 3	100,000	Use 50%+ of Tier 2 limit within 7 days with GREEN quality.
Unlimited	Unlimited	Use 50%+ of Tier 3 limit within 7 days with GREEN quality.

Tier Progression Rules

ℹ

How to Upgrade: To move to the next tier, you must send messages to at least 50% of your current limit of unique customers within a 7-day rolling window, while maintaining a GREEN quality rating. Tier upgrades happen automatically.

⚠

Tier Downgrades: If your quality rating drops to RED, your messaging limit may be reduced to a lower tier. In severe cases, your phone number may be flagged or restricted. Monitor your quality rating regularly in the WhatsBizAPI dashboard or Meta Business Manager.

Maintaining Quality

Follow these practices to keep your quality rating at GREEN:

Practice	Impact
Only message users who have opted in	Reduces blocks and reports significantly.
Use clear, relevant template content	Prevents users from marking messages as spam.
Respect message frequency preferences	Avoids user fatigue and negative feedback.
Provide easy opt-out mechanisms	Users who can unsubscribe are less likely to block you.
Target the right audience segments	Relevant messages receive better engagement and fewer complaints.