📚 API Documentation

Build with Zaple API

Comprehensive API documentation to integrate WhatsApp Business API into your applications. Send messages, manage catalogs, and automate at scale.

🚀 Getting Started

Introduction

Welcome to the Zaple.ai API documentation. Our RESTful API allows you to integrate WhatsApp Business capabilities directly into your applications, enabling automated messaging, contact management, catalog sync, and more.

Base URL

https://app.zaple.ai/api/v2/

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Authentication

Zaple uses API key and secret authentication. Include these headers in every request:

// Required Headers
Zaple-Api-Key: your_api_key
Zaple-Api-Secret: your_api_secret
Content-Type: application/json

💡 Tip: Get your API credentials from Settings → API & Developer

💬 Messaging API

POST /api/v2/send-template-message

Send a pre-approved WhatsApp template message to a single recipient. The required fields in the request body vary by template type. Select your template type below to see the precise parameters and request format.

For simple templates with no variables and no media header.

Parameter Type Required Description
template_id string Required Template ID from your library
country_code string Required Country code without + (e.g., "91")
send_to string Required Recipient phone number
curl --location 'https://app.zaple.ai/api/v2/send-template-message' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --form 'template_id="21460221760533881199999"' --form 'country_code="91"' --form 'send_to="1234567890"'

Response

200 OK
{
    "status": "Message sent successfully.",
    "message_id": "x927831064523907185K9CDMYNReFgHIPWz"
}
GET /api/v2/template-details

Retrieve details of all approved message templates in your account.

Example (cURL)

curl --location 'https://app.zaple.ai/api/v2/template-details' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret'

Response

200 OK
{
  "data": [
    {
      "name": "Order cancle",
      "template_id": "443657917386635402102430",
      "content": {
        "components": [
          {
            "type": "BODY",
            "text": "Hi, this is to confirm we have successfully canceled your recent order {{1}}.
Thank you.",
            "example": {
              "body_text": [["order"]]
            }
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "PHONE_NUMBER",
                "text": "Call Now",
                "phone_number": "+911234567890"
              }
            ]
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "UTILITY"
      },
      "type": "UTILITY",
      "status": "APPROVED",
      "status_update_reason": "NONE",
      "header_type": "none"
    }
  ],
  "links": {
    "first": "https://app.zaple.ai/api/v2/template-details?page=1",
    "last": "https://app.zaple.ai/api/v2/template-details?page=10",
    "prev": null,
    "next": "https://app.zaple.ai/api/v2/template-details?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "links": [
      {"url": null, "label": "« Previous", "active": false},
      {"url": "https://app.zaple.ai/api/v2/template-details?page=1", "label": "1", "active": true},
      {"url": "https://app.zaple.ai/api/v2/template-details?page=10", "label": "10", "active": false},
      {"url": "https://app.zaple.ai/api/v2/template-details?page=2", "label": "Next »", "active": false}
    ],
    "path": "https://app.zaple.ai/api/v2/template-details",
    "per_page": 10,
    "to": 10,
    "total": 96
  }
}
GET /api/v2/message-status

Check the delivery status of a sent message using its message ID.

Example (cURL)

curl --location 'https://app.zaple.ai/api/v2/message-status?message_id=Zhyfge1254HGYRTFGDdsw8545244HUETE' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --header 'Content-Type: application/json' --header 'Accept: application/json'

Response

200 OK
{
   "sent_at": 2026-09-05 18:53:00,
   "delivered_at": 2026-09-05 18:53:12,
   "read_at": 2026-09-05 18:54:24,
   "is_failed": 0,
   "mobile_number": 919876543210
}
GET /api/v2/message-count

Get message count and usage statistics for your account.

Parameter Type Required Description
from_date string Optional Format = "yyyy-mm-dd hh:mm:ss"
to_date string Optional Format = "yyyy-mm-dd hh:mm:ss"

Example (cURL)

curl --location 'https://app.zaple.ai/api/v2/message-count' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --header 'Content-Type: application/json' --header 'Accept: application/json'

Response

200 OK
{
    "total_messages": 12547,
    "sent": 12500,
    "read": 11425
}

Messaging API (v3)

POST /api/v3/send-template-message

Send a pre-approved WhatsApp template message using multipart/form-data for advanced configuration including direct file uploads, quick reply payloads, and arbitrary callback tracking data.

💡 v3 vs v2: v3 uses form-data (not JSON), supports direct file uploads via media_file, and adds quick_reply_payloadN and biz_opaque_callback_data fields. Use v3 when you need any of these capabilities.

For simple templates with no variables and no media header.

Parameter Type Required Description
template_id string Required Template ID from your library
country_code string Required Country code without + (e.g., "91")
send_to string Required Recipient phone number
quick_reply_payloadN string Optional Custom payload for quick replies
biz_opaque_callback_data string Optional Arbritrary tracking data
curl --location 'https://app.zaple.ai/api/v3/send-template-message' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --form 'template_id="21460221760533881199999"' --form 'country_code="91"' --form 'send_to="1234567890"' --form 'quick_reply_payload1="approve_67_schedule"' --form 'quick_reply_payload2="reject_67_schedule"' --form 'biz_opaque_callback_data="{"appointment_id":52,"message_id":528}"'

Response

200 OK
{
    "status": "Message sent successfully.",
    "message_id": "x927831064523907185K9CDMYNReFgHIPWz"
}

Webhook Responses (v3)

When using v3 with opaque callback data or quick reply buttons, you will receive more detailed webhook events.

1. Message Sent Status

Includes biz_opaque_callback_data returned natively from WhatsApp.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1147896940776789",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "911234567890",
              "phone_number_id": "838463922683351"
            },
            "statuses": [
              {
                "id": "wamid.HBgMOTE4ODY2MjMwNjYzFQIAERgSNzc2RUEzMEQwQUQ1NzhGNjZCAA==",
                "status": "sent",
                "timestamp": "1771854964",
                "recipient_id": "911234567890",
                "biz_opaque_callback_data": "{\"type\":\"zaple_api_call\",\"user_id\":\"56\",\"extra\":{\"send_to\":\"911234567890\",\"appointment_id\":\"52\",\"message_id\":\"528\"}}",
                "pricing": {
                  "billable": false,
                  "pricing_model": "PMP",
                  "category": "utility",
                  "type": "free_customer_service"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

2. Button Payload Webhook

Received when the user taps on your quick reply button. Includes the button payload originally passed in the send request.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1147896940776789",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "911234567890",
              "phone_number_id": "838463922683351"
            },
            "contacts": [
              {
                "profile": {
                  "name": "test"
                },
                "wa_id": "911234567890"
              }
            ],
            "messages": [
              {
                "context": {
                  "from": "911234567890",
                  "id": "wamid.HBgMOTE4ODY2MjMwNjYzFQIAERgSNzc2RUEzMEQwQUQ1NzhGNjZCAA=="
                },
                "from": "911234567890",
                "id": "wamid.HBgMOTE4ODY2MjMwNjYzFQIAEhgWM0VCMEM3MDk5RTEyQkMyRDMwMjE5NAA=",
                "timestamp": "1771855045",
                "type": "button",
                "button": {
                  "payload": "approve_67_schedule",
                  "text": "Approve"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

💬 Service Messages API

Generate and send new service messages.

Generate New Service Messages API

POST /api/v2/send-service-message

Send rich service messages over WhatsApp. Choose a template type and the payload validators for text, image, audio, video, location, or contact headers appear in the same tab.

Send a plain text service message.

Parameter Type Required Description
country_code string Required Country code without + (e.g., "91")
send_to string Required Recipient mobile number
type string Required Message type. Use text
text string Required Text message content

Request

curl --location 'https://app.zaple.ai/api/v2/send-service-message' --header 'Zaple-Api-Key: you_zaple_api_key' --header 'Zaple-Api-Secret: you_zaple_api_secret' --form 'country_code="91"' --form 'send_to="1234567890"' --form 'type="text"' --form 'text="hello, how are you?"'

Response

200 OK
{"status": Message Sent Successfully,  "message_id": "58761684655asdsad"}

📦 Batch API

Send messages to multiple recipients efficiently using batch operations.

POST /api/v2/lists

Create a new batch list for bulk messaging. Upload contacts with their template variables.

Parameters

Parameter Type Required Description
name string Required Name of the batch list

Request

curl --location 'https://app.zaple.ai/api/v2/lists' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --form 'name="Zaple - Batch API"'

Response

200 Created
{
    "status": true,
    "list_id": 12345,
    "message": "List created successfully."
}
POST /api/v2/messages/batch

Trigger a batch message send for an existing list using a template.

Request

curl --location 'https://app.zaple.ai/api/v2/messages/batch' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --form 'template_id="231245217727840054064050"' --form 'list_id="6574"'

Response

200 OK
{
    "status": true,
    "batch_id": "batch_17369325432094653",
    "message": "Batch message request submitted successfully."
}
POST /api/v2/lists/{list_id}/contacts

Create or update contacts inside a batch list.

Request

curl --location 'https://app.zaple.ai/api/v2/lists/6574/contacts' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --header 'Content-Type: application/json' --data '{
  "contacts": [
    {
      "country_code": "91",
      "phone_number": "9876543210",
      "name": "John Doe"
    },
    {
      "country_code": "1",
      "phone_number": "5550123",
      "name": "Jane Smith"
    }
  ]
}
'

Response

200 OK
{
    "success": true,
    "message": "Contacts added/updated successfully."
}
GET /api/v2/batch/{id}/status

Check the processing status of a batch operation.

Request

curl --location --request GET 'https://app.zaple.ai/api/v2/messages/batch/batch_1772790945798814/status' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --form 'template_id="231245217727840054064050"' --form 'list_id="6574"'

Response

200 OK
{
    "success": true,
    "batch_id": "batch_173693254320885494653",
    "status": "completed",
    "total_messages": 500,
    "sent": 307,
    "delivered": 298,
    "read": 253,
    "failed": 0
}
GET /api/v2/batch/{id}/details

Get detailed information about a batch including delivery stats and failed messages.

Request

curl --location --request GET 'https://app.zaple.ai/api/v2/messages/batch/batch_1772790945798814/details' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --form 'template_id="231245217727840054064050"' --form 'list_id="6574"'

Response

200 OK
{
  "success": true,
  "batch_id": "batch_17369325432094653",
  "status": "completed",
  "total_messages": 500,
  "messages": {
    "data": [
      {
        "phone_number": 911234567890,
        "is_sent": 1,
        "sent_at": "2024-09-05 18:53:00",
        "is_delivered": 1,
        "is_failed": 0
      }
    ],
    "links": {
      "first": "...",
      "last": "...",
      "prev": null,
      "next": "..."
    },
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 90,
      "per_page": 20,
      "to": 20,
      "total": 1800
    }
  }
}
DELETE /api/v2/lists/{id}

Delete a batch list and all associated records.

Request

curl --location --request DELETE 'https://app.zaple.ai/api/v2/lists/6574' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --form 'template_id="231245217727840054064050"' --form 'list_id="6574"'

Response

200 OK
{
  "status": true,
  "message": "List deleted successfully."
}

🛍️ Catalog API

Manage product catalogs and sync with WhatsApp Commerce.

GET /api/v2/catalogs

Get all catalogs for the authenticated user.

Request

curl --location 'https://app.zaple.ai/api/v2/catalogs' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret'

Response

200 OK
{
  "success": true,
  "data": [
    {
      "id": "1514923905937285",
      "name": "Summer Collection",
      "vertical": "commerce"
    }
  ]
}
POST /api/v2/catalogs

Create a new product catalog.

Request

curl --location 'https://app.zaple.ai/api/v2/catalogs' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --form 'name="Zaple - Batch API"'

Response

200 OK
{
  "success": true,
  "data": {
    "id": "1514923905937285",
    "name": "New Catalog"
  },
  "message": "Catalog created successfully"
}
POST /api/v2/catalogs/{catalog_id}/connect

Connect a catalog to your WhatsApp Business Account.

Parameters

Parameter Type Required Description
catalog_id string Required ID of the catalog to connect

Examples

curl --location --request POST 'https://app.zaple.ai/api/v2/catalogs/4077255635858041/connect' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret'

Response

200 OK
{
  "success": true,
  "data": {
    "status": "connected"
  },
  "message": "Catalog connected successfully"
}
POST /api/v2/catalogs/{catalog_id}/disconnect

Disconnect a catalog from your WhatsApp Business Account.

Parameters

Parameter Type Required Description
catalog_id string Required ID of the catalog to disconnect

Examples

curl --location --request POST 'https://app.zaple.ai/api/v2/catalogs/4077255635858041/disconnect' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret'

Response

200 OK
{
  "success": true,
  "data": {
    "success": true
  },
  "message": "Catalog disconnected successfully"
}
GET /api/v2/catalogs/{catalog_id}/products

List all products in a catalog.

Request

curl --location 'https://app.zaple.ai/api/v2/catalogs/4077255635858041/products' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret'

Response

200 OK
{
  "success": true,
  "data": [
    {
      "id": "41734658883668",
      "name": "Premium T-Shirt",
      "retailer_id": "TSH-001",
      "price": "599",
      "currency": "INR",
      "image_url": "https://example.com/image.jpg"
    }
  ]
}
POST /api/v2/catalogs/{catalog_id}/products

Create a new product inside a specific catalog.

Request

curl --location 'https://app.zaple.ai/api/v2/catalogs/4077255635858041/products' --header 'Zaple-Api-Key: your_zaplel_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --header 'Content-Type: application/json' --data '{
  "name": "Men'''s Classic Blue Jeans",
  "retailer_id": "SKU-12345",
  "price": 1299.00,
  "currency": "INR",
  "image_url": "https://example.com/images/jeans-main.jpg",
  "description": "High-quality slim fit blue jeans made from 100% organic cotton.",
  "brand": "Zaple Fashion",
  "category": "Apparel & Accessories > Clothing > Pants > Jeans",
  "condition": "new",
  "availability": "in stock",
  "url": "https://example.com/products/mens-classic-blue-jeans",
  "gender": "male",
  "size": "32",
  "color": "Blue",
  "material": "Denim",
  "pattern": "Solid",
  
  "sale_price": 999.00,
  "sale_price_start_date": "2024-03-01T00:00:00Z",
  "sale_price_end_date": "2024-03-31T23:59:59Z",
  
  "additional_image_urls": [
    "https://example.com/images/jeans-back.jpg",
    "https://example.com/images/jeans-side.jpg"
  ],
  "inventory": 50,
  "product_type": "Apparel",
  "origin_country": "IN",
  "visibility": "published"
}
'

Response

201 Created
{
  "success": true,
  "data": {
    "id": "41734658883668",
    "retailer_id": "TSH-001"
  },
  "message": "Product created successfully"
}
GET /api/v2/catalogs/commerce-settings

Retrieve your commerce configuration such as currency, country and visibility defaults.

Request

curl --location 'https://app.zaple.ai/api/v2/commerce/settings' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret'

Response

200 OK
{
  "success": true,
  "data": {
    "catalog_id": "1514923905937285",
    "is_catalog_connected": true,
    "shop_status": "enabled",
    "cart_enabled": true
  }
}
POST /api/v2/catalogs/{catalog_id}/visibility

Toggle whether a catalog is visible to customers.

Request

curl --location 'https://app.zaple.ai/api/v2/catalogs/4077255635858041/visibility' --header 'Zaple-Api-Key: your_zaple_api_key' --header 'Zaple-Api-Secret: your_zaple_api_secret' --header 'Content-Type: application/json' --data '{
    "visible": true
}'

Response

200 OK
{
  "success": true,
  "data": {
    "success": true
  },
  "message": "Catalog visibility updated successfully"
}

🔔 Webhooks

Receive real-time notifications for messages, delivery updates, and more.

Webhook Setup

Configure your webhook URL in Settings → Webhooks

// Your server should accept POST requests
// with JSON body containing event data
{
  "event": "message.received",
  "timestamp": "2024-02-07T12:00:00Z",
  "data": { ... }
}

Ready to Start Building?

Get your API keys and start integrating WhatsApp into your application today.