WhatsApp Business Platform API

1. Overview

An integration follows a fixed order. Create a template and wait for Meta to approve it, verify the approval, then send — either to a single number through the message sender, or to a list through the campaign creator. Nothing can be sent from an unapproved template.

BASE URL — https://app.fonada.ai/functions/v1

1.1 The 24-hour conversation window

Free-form messages — text, image, document, and interactive — may only be sent within 24 hours of the customer's last inbound message. Once that window closes, the send fails with error 131047 and a template message must be used instead. Template messages, including every campaign send, are not subject to the window.

1.2 Conventions used in this document

2. Authentication

All endpoints accept a bearer token in the Authorization header. Three credential types are supported; use the API key for server-to-server integrations.

Authorization: Bearer fsk_your_api_key_here
Content-Type: application/json

accountId is derived from the token and must not be included in template payloads. For message sends with an fsk_ key or JWT, account_id may be omitted when exactly one active WABA is linked to your user; include it in the body otherwise.

3. Template management

3.1 List templates

GET /whatsapp_templates — 100 requests / minute

Returns the templates available to your account. Use it to confirm the exact, case-sensitive template name before a send.

curl -G 'https://app.fonada.ai/functions/v1/whatsapp_templates' \
-H 'Authorization: Bearer fsk_your_key_here' \
--data-urlencode 'status=APPROVED'

{ "success": true, "data": { "templates": [ ... ] }, "count": N }

3.2 Create a template

POST /whatsapp_template_manager — "action": "create"

A template defines the exact message structure Meta will approve. Once approved, reference it by name from campaigns and message sends.

Rules before creating

Payload structure

{
  "action": "create",
  "templateData": {
    "name": "your_template_name",
    "category": "MARKETING",
    "language": "en_US",
    "components": [ ... ],
    "sample_values": { "1": "example value" }
  }
}

accountId is auto-derived from your token — do not include it.

Example A — body-only template

A single-paragraph message with one variable, suitable for OTPs, order updates, or welcome messages.

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_template_manager' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{
  "action": "create",
  "templateData": {
    "name": "welcome_new_customer",
    "category": "MARKETING",
    "language": "en_US",
    "components": [{
      "type": "BODY",
      "text": "Welcome {{1}}! Thank you for joining us."
    }],
    "sample_values": { "1": "John Doe" },
    "include_optout": true,
    "optout_message": "Reply STOP to unsubscribe"
  }
}'

Example B — header, body, and footer

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_template_manager' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{
  "action": "create",
  "templateData": {
    "name": "order_confirmed_full",
    "category": "UTILITY",
    "language": "en_US",
    "components": [
      { "type": "HEADER", "format": "TEXT", "text": "Order Confirmed" },
      { "type": "BODY",   "text": "Hi {{1}}, your order #{{2}} has been confirmed.\nTotal: Rs. {{3}}\nExpected delivery: {{4}}" },
      { "type": "FOOTER", "text": "Thank you for shopping with us!" }
    ],
    "sample_values": { "1": "Priya Sharma", "2": "ORD-12345", "3": "1,999", "4": "Feb 28, 2026" }
  }
}'

Example C — template with action buttons

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_template_manager' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{
  "action": "create",
  "templateData": {
    "name": "delivery_update_with_cta",
    "category": "UTILITY",
    "language": "en_US",
    "components": [
      { "type": "BODY", "text": "Your order #{{1}} is out for delivery! Estimated arrival: {{2}}" },
      { "type": "BUTTONS", "buttons": [
        { "type": "URL",          "text": "Track Order",  "url": "https://yourstore.com/track/{{1}}" },
        { "type": "PHONE_NUMBER", "text": "Call Support", "phone_number": "+910000000000" }
      ]}
    ],
    "sample_values": { "1": "ORD-98765", "2": "Today by 6 PM" }
  }
}'

Component constraints

Button types

Success response

{
  "success": true,
  "template": {
    "id": "7119e2f3-7469-4cbe-a85b-5e7cf614ae03",
    "template_name": "order_confirmed_full",
    "status": "PENDING",
    "category": "UTILITY",
    "language": "en_US",
    "created_at": "2026-02-26T12:00:00Z"
  },
  "message": "Template submitted to WhatsApp for review. Approval typically takes 24-48 hours."
}

Common errors

3.3 Get template status

POST /whatsapp_template_manager — "action": "get_status"

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_template_manager' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{ "action": "get_status", "templateName": "order_confirmed_full" }'

{
  "success": true,
  "template": {
    "id": "7119e2f3-7469-4cbe-a85b-5e7cf614ae03",
    "template_name": "order_confirmed_full",
    "status": "APPROVED",
    "rejection_reason": null,
    "quality_score": "HIGH"
  }
}

3.4 Sync templates from Meta

POST /whatsapp_template_manager — "action": "sync"

Pulls the latest template statuses from Meta into the Fonada database.

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_template_manager' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{ "action": "sync" }'

3.5 Delete a template

POST /whatsapp_template_manager — "action": "delete"

A template in use by an active campaign cannot be deleted. Stop the campaign first.

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_template_manager' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{ "action": "delete", "templateName": "old_promo_v1" }'

4. Message sending

POST /whatsapp_message_sender — 80 requests / second

Sends an individual message to one WhatsApp number. All four message types below are free-form and therefore restricted to the 24-hour conversation window described in section 1.1.

4.1 Text message

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_message_sender' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{
  "to": "919876543210",
  "message": {
    "type": "text",
    "text": { "body": "Hello! Your order has been dispatched and will arrive by tomorrow." }
  }
}'

{
  "success": true,
  "data": {
    "message_id": "wamid.HBgLOTE5ODc2NTQzMjEwFQIAERgS...",
    "wa_id": "919876543210",
    "status": "sent"
  },
  "performance": { "total_time_ms": 1682 }
}

4.2 Image message

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_message_sender' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{
  "to": "919876543210",
  "message": {
    "type": "image",
    "image": {
      "link": "https://yourcdn.com/products/item-001.jpg",
      "caption": "Your ordered item — arrives by tomorrow!"
    }
  }
}'

Requirements: JPEG or PNG, maximum 5 MB, caption up to 1,024 characters.

4.3 Document message

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_message_sender' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{
  "to": "919876543210",
  "message": {
    "type": "document",
    "document": {
      "link": "https://yourcdn.com/invoices/INV-2026-001.pdf",
      "filename": "Invoice_March2026.pdf",
      "caption": "Your invoice for order ORD-12345"
    }
  }
}'

Requirements: PDF, DOC, DOCX, XLS, XLSX, PPT, or PPTX, maximum 100 MB.

4.4 Interactive buttons

curl -X POST 'https://app.fonada.ai/functions/v1/whatsapp_message_sender' \
-H 'Authorization: Bearer fsk_your_key_here' \
-H 'Content-Type: application/json' \
-d '{
  "to": "919876543210",
  "message": {
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": { "text": "Your order ORD-12345 is ready for pickup. Confirm?" },
      "action": {
        "buttons": [
          { "type": "reply", "reply": { "id": "confirm_pickup", "title": "Yes, confirm" } },
          { "type": "reply", "reply": { "id": "reschedule",     "title": "Reschedule"   } },
          { "type": "reply", "reply": { "id": "cancel_order",   "title": "Cancel order" } }
        ]
      }
    }
  }
}'

• Minimum 1 and maximum 3 buttons.
• title is limited to 20 characters.
• id is returned in the webhook when tapped — use it to identify the customer's choice.
• Must be sent within the 24-hour customer-initiated window.

4.5 Message status values

Common errors on message sends

5. Campaigns

POST /whatsapp_campaign_creator

Use this endpoint to send the same approved template to many recipients in one call, with per-recipient variable values. The message sender targets a single number; the campaign creator accepts an audience list and handles bulk dispatch.

curl --location 'https://app.fonada.ai/functions/v1/whatsapp_campaign_creator' \
--header 'Authorization: Bearer fsk_your_key_here' \
--header 'Content-Type: application/json' \
--data '{
  "campaign_name": "test_abc1",
  "template_name": "test_abcd",
  "audience_rows": [
    { "phone": "917983272926", "BODY_1": "test1" },
    { "phone": "917428346262", "BODY_1": "test1" }
  ]
}'

{
  "success": true,
  "campaign": {
    "id": "c3a1e2f4-9b7d-4e6a-a123-0d8f1e5c2b90",
    "campaign_name": "test_abc1",
    "template_name": "test_abcd",
    "status": "launched",
    "total_recipients": 2,
    "queued_at": "2026-04-29T10:00:00Z"
  }
}

Common campaign errors

6. Error reference

6.1 HTTP status codes

6.2 WhatsApp error codes

These appear in the error_data.code field when Meta rejects a message.

6.3 Troubleshooting

7. Support

When raising a ticket, quote the message_id for a single send or the campaign id for a bulk send — these identify the exact dispatch in platform logs.

Appendix A — Field formats and rate limits

Phone number format

Date and time format (ISO 8601, UTC)

Template name format

WhatsApp messaging tiers (enforced by Meta)

API request limits (enforced by Fonada)

Appendix B — Revision history