📚 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: zaple_your_api_key_here' \
--header 'Zaple-Api-Secret: zaple_your_api_secret_here' \
--header 'Content-Type: application/json' \
--data '{
    "template_id": "123456789012345678901234",
    "country_code": "91",
    "send_to": "9876543210"
  }'
GET /api/v2/template-details

Retrieve details of all approved message templates in your account.

curl -X GET https://app.zaple.ai/api/v2/template-details \
  -H "Zaple-Api-Key: your_api_key" \
  -H "Zaple-Api-Secret: your_api_secret"
GET /api/v2/message-status

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

Example (cURL)

curl --request GET \
    --get "https://app.zaple.ai/api/v2/message-status" \
    --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" \
    --data "{\"message_id\": \"4U49782356VCFD849938PJxwzW8sSkEfEpTk\"}"
GET /api/v2/message-count

Get message count and usage statistics for your account.

Example (cURL)

curl --request GET \
    --get "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"

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 Arbitrary tracking data payload
curl --location 'https://app.zaple.ai/api/v3/send-template-message' --header 'Zaple-Api-Key: zaple_{your_api_key}' --header 'Zaple-Api-Secret: zaple_{your_api_secret}' --form 'template_id="491022917713968981540355"' --form 'send_to="918866230663"' --form 'country_code="91"'

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": "919724509724",
              "phone_number_id": "838463922683351"
            },
            "statuses": [
              {
                "id": "wamid.HBgMOTE4ODY2MjMwNjYzFQIAERgSNzc2RUEzMEQwQUQ1NzhGNjZCAA==",
                "status": "sent",
                "timestamp": "1771854964",
                "recipient_id": "918866230663",
                "biz_opaque_callback_data": "{\"type\":\"zaple_api_call\",\"user_id\":\"56\",\"extra\":{\"send_to\":\"918866230663\",\"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": "919724509724",
              "phone_number_id": "838463922683351"
            },
            "contacts": [
              {
                "profile": {
                  "name": "~smit"
                },
                "wa_id": "918866230663"
              }
            ],
            "messages": [
              {
                "context": {
                  "from": "919724509724",
                  "id": "wamid.HBgMOTE4ODY2MjMwNjYzFQIAERgSNzc2RUEzMEQwQUQ1NzhGNjZCAA=="
                },
                "from": "918866230663",
                "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 a new service message. The type can be text, image, video, or document. For media types (image, video, document), a file form field is required instead of text.

Example Request (cURL)

curl --location 'https://app.zaple.ai/api/v2/send-service-message' \
--header 'Zaple-Api-Key: zaple_{your_api_key}' \
--header 'Zaple-Api-Secret: zaple_{your_api_secret}' \
--form 'send_to="8866230663"' \
--form 'country_code="91"' \
--form 'type="text"' \
--form 'text="hello"'

📦 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
GET /api/v2/batch/{id}/status

Check the processing status of a batch operation.

Example (cURL)

curl --request GET \
    --get "https://app.zaple.ai/api/v2/messages/batch/batch_17369325432094653/status" \
    --header "Zaple-Api-Key: your zaple api key" \
    --header "Zaple-Api-Secret: your zaple api secret" \
    --header "Accept: application/json"
GET /api/v2/batch/{id}/details

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

Example (cURL)

curl --request GET \
    --get "https://app.zaple.ai/api/v2/messages/batch/batch_17369325432094653/details?limit=50" \
    --header "Zaple-Api-Key: your zaple api key" \
    --header "Zaple-Api-Secret: your zaple api secret" \
    --header "Accept: application/json"
DELETE /api/v2/lists/{id}

Delete a batch list and all associated records.

Example (cURL)

curl --request DELETE \
    "https://app.zaple.ai/api/v2/lists/batch_17369325432094653" \
    --header "Zaple-Api-Key: your zaple api key" \
    --header "Zaple-Api-Secret: your zaple api secret" \
    --header "Accept: application/json"

🛍️ Catalog API

Manage product catalogs and sync with WhatsApp Commerce.

GET /api/v2/catalogs

Get all catalogs for the authenticated user.

Example (cURL)

curl --request GET \
    --get "https://app.zaple.ai/api/v2/catalogs" \
    --header "Zaple-Api-Key: your zaple api key" \
    --header "Zaple-Api-Secret: your zaple api secret" \
    --header "Accept: application/json"
POST /api/v2/catalogs

Create a new product catalog.

Example (cURL)

curl --request POST \
    "https://app.zaple.ai/api/v2/catalogs" \
    --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" \
    --data '{"name": "Summer Collection 2026"}'
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

Example (cURL)

curl --request POST \
    "https://app.zaple.ai/api/v2/catalogs/cat_8812930445/connect" \
    --header "Zaple-Api-Key: your zaple api key" \
    --header "Zaple-Api-Secret: your zaple api secret" \
    --header "Accept: application/json"
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

Example (cURL)

curl --request POST \
    "https://app.zaple.ai/api/v2/catalogs/cat_8812930445/disconnect" \
    --header "Zaple-Api-Key: your zaple api key" \
    --header "Zaple-Api-Secret: your zaple api secret" \
    --header "Accept: application/json"
GET /api/v2/catalogs/{catalog_id}/products

List all products in a catalog.

Example (cURL)

curl --request GET \
    --get "https://app.zaple.ai/api/v2/catalogs/cat_8812930445/products" \
    --header "Zaple-Api-Key: your zaple api key" \
    --header "Zaple-Api-Secret: your zaple api secret" \
    --header "Accept: application/json"

🔔 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.