SocialAPI | Enterprise WhatsApp Business API platform

Endpoints & Guides11

Quick Start Postman Collection Authentication Templates Campaigns Send Messages Product Catalog Payment Requests Outbound Webhooks Contacts Workspace & Profile

Get Your API Key

Create a free account to generate your Bearer token and start integrating WhatsApp Cloud API.

Create Free Account Sign In

Jump to Section11 sections

Quick Start

Welcome to the SocialAPI API. Build powerful WhatsApp messaging integrations directly into your applications.

Preferred Language:

Jump to:

Postman Collection

v2.1

Accelerate your development by importing our official Postman Collection. It includes pre-configured requests for all available endpoints, saving you time on manual setup.

API Collection

Contains all API v1 endpoints with example payloads and dynamic variables.

Environment Config

Rapidly switch between environments using our pre-defined variables.

How to Import

Download both the **Collection** and **Environment** JSON files above.
Open Postman and click the **Import** button in the top left.
Drag and drop both files into the import area.
Select the imported environment and replace `YOUR_API_TOKEN_HERE` with your actual token.

Authentication

Authenticate your requests by including your API token in the Authorization header.

Authorization: Bearer <YOUR_TOKEN>

Get Your Token

Security Notice: Treat your API tokens like passwords. Do not share them or commit them to public repositories. Find and generate your keys in Developer Settings.

Templates

GET/api/v1/templates

Retrieve a list of all WhatsApp templates available for your company.

Lang:

curl -X GET "/api/v1/templates" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

POST/api/v1/templates

Create a new WhatsApp Template. To add an attachment (media), specify a HEADER component with format IMAGE, VIDEO, or DOCUMENT.

Lang:

curl -X POST "/api/v1/templates" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my_media_template",
  "category": "MARKETING",
  "language": "en_US",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": [
          "<upload_handle_id>"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}, check out this image!",
      "example": {
        "body_text": [
          [
            "John"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Reply STOP to unsubscribe"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Yes, I am interested"
        }
      ]
    }
  ]
}'

Request Parameters

Field	Type	Required	Description
`name`	string	Required	Unique template name (lowercase letters, numbers, and underscores only).
`category`	string	Required	Template category: "MARKETING", "UTILITY", or "AUTHENTICATION".
`language`	string	Required	Template locale code (e.g. "en_US", "es_ES").
`components`	object[]	Required	Array of template component objects (HEADER, BODY, FOOTER, BUTTONS).
`whatsapp_number_key`	string	Optional	Unique 12-char key for targeted WhatsApp number routing.

Multi-Number Support: All messaging and campaign endpoints accept an optional whatsapp_number_key. If omitted, your default WhatsApp account will be used.

Campaigns

GET/api/v1/campaigns

List all your campaigns.

Lang:

curl -X GET "/api/v1/campaigns" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

GET/api/v1/campaigns/123

Get details of a specific campaign, including its status and statistics.

Lang:

curl -X GET "/api/v1/campaigns/123" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

POST/api/v1/campaigns

Create a draft campaign. You can specify precise recipients for testing or transactional use.

Monthly Unique Contacts (MUC) Limit: Campaigns are validated against your plan's unique recipient messaging quota. If the campaign recipients would push your usage over the limit, the request will be rejected (HTTP 400) and you will receive an upgrade notification email. Stored contact records are never blocked — only message sending is enforced.

Lang:

curl -X POST "/api/v1/campaigns" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Summer Sale Blast",
  "template_name": "hello_world",
  "language": "en_US",
  "recipients": [
    "919876543210"
  ],
  "whatsapp_number_key": "AK7MXP2RBNCQ",
  "variables": [
    "John",
    "10% Off"
  ],
  "header_media_url": "https://example.com/promo.jpg"
}'

Request Parameters

Field	Type	Required	Description
`name`	string	Required	Display name for the campaign (e.g. "Summer Sale Blast").
`template_name`	string	Required	Approved WhatsApp template to use for the broadcast.
`recipients`	string[]	Optional	Optional explicit phone numbers to send to directly. If omitted, uses contact group / list.
`variables`	string[]	Optional	Array of body variable fallback substitutions {{1}}, {{2}}, etc.
`header_media_url`	string	Optional	Public media URL for header image/video/document.
`whatsapp_number_key`	string	Optional	Unique 12-char key for targeted WhatsApp number routing.
`language`	string	Optional	Template language code (e.g. "en_US").

Dynamic Variables & Media

You can optionally pass global variables (array of strings for {{1}}, {{2}}), header_variable, header_media_url, and header_media_type the exact same way as the Send Template endpoint. These act as fallbacks if the system cannot auto-resolve placeholders from your contact list.

POST/api/v1/campaigns/123/send

Trigger the sending process for a campaign.

Lang:

curl -X POST "/api/v1/campaigns/123/send" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json"

Send Messages

Try in Direct Send Console

POST/api/v1/messages/text

Send a standard text message to a user.

Lang:

curl -X POST "/api/v1/messages/text" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "1234567890",
  "text": "Hello, this is a test message from API.",
  "whatsapp_number_key": "AK7MXP2RBNCQ"
}'

POST/api/v1/messages/attachment

Send media (image, video, document, audio) via URL.

Lang:

curl -X POST "/api/v1/messages/attachment" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "1234567890",
  "type": "image",
  "url": "https://example.com/image.png",
  "caption": "Check this out!",
  "whatsapp_number_key": "AK7MXP2RBNCQ"
}'

Request Parameters

Field	Type	Required	Description
`to`	string	Required	Recipient phone number with country code without plus sign (e.g. "919876543210").
`type`	string	Required	Media format type: "image", "video", "audio", or "document".
`url`	string	Required	Direct accessible URL of the file to transmit.
`caption`	string	Optional	Optional text description to show alongside the media.
`whatsapp_number_key`	string	Optional	Unique 12-char key for targeted WhatsApp number routing.

POST/api/v1/messages/template

Send a template message with dynamic variables. We support a simplified payload format for easy integration, with optional scheduling for future dispatch.

Lang:

curl -X POST "/api/v1/messages/template" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "1234567890",
  "template_name": "welcome_user",
  "language": "en_US",
  "variables": [
    "John",
    "123"
  ],
  "header_variable": "Order #456",
  "header_media_url": "https://example.com/invoice.pdf",
  "header_media_type": "document",
  "whatsapp_number_key": "AK7MXP2RBNCQ",
  "scheduled_at": "2026-08-17 19:30:00"
}'

Request Parameters

Field	Type	Required	Description
`to`	string	Required	Recipient phone number including country code without plus sign (e.g. "919876543210").
`template_name`	string	Required	The approved template name configured on your WhatsApp account.
`variables`	string[]	Optional	Array of variable substitutions for template body {{1}}, {{2}}, etc.
`header_variable`	string	Optional	Text substitution for {{1}} placeholder in a text header.
`header_media_url`	string	Optional	Direct public URL for media attachment (image, video, or PDF document).
`header_media_type`	string	Optional	Media format: "image", "video", or "document". Defaults to "image".
`whatsapp_number_key`	string	Optional	Unique 12-char identifier for multi-number routing from Developer Settings.
`language`	string	Optional	Template language locale (e.g. "en_US"). Defaults to "en_US".
`scheduled_at`	string	Optional	Future dispatch date-time (e.g. "2026-08-17 19:30:00" or ISO 8601). Enqueued automatically.

POST/api/v1/messages/typing

Display Meta's native animated “typing...” indicator in the customer's WhatsApp chat and simultaneously mark the message as read (blue ticks). This indicator stays active for up to 25 seconds or until your outgoing reply message is delivered.

Lang:

curl -X POST "/api/v1/messages/typing" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSM0EzNjUyNTc5NEIxRkQ3QkE1AA==",
  "whatsapp_account_id": "AK7MXP2RBNCQ"
}'

Request Parameters

Field	Type	Required	Description
`message_id`	string	Required	The incoming WhatsApp message ID (wamid.HBg...) from inbound webhook payload (message.received).
`whatsapp_account_id`	string	Optional	Unique 12-char identifier (or whatsapp_number_key) from Developer Settings for multi-number routing.

POST/api/v1/messages/read

Explicitly mark an incoming customer message as read (displaying blue ticks on the sender's phone) without triggering the typing indicator animation.

Lang:

curl -X POST "/api/v1/messages/read" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSM0EzNjUyNTc5NEIxRkQ3QkE1AA==",
  "whatsapp_account_id": "AK7MXP2RBNCQ"
}'

Request Parameters

Field	Type	Required	Description
`message_id`	string	Required	The incoming WhatsApp message ID (wamid.HBg...) to mark with read receipts (blue ticks).
`whatsapp_account_id`	string	Optional	Unique 12-char identifier (or whatsapp_number_key) from Developer Settings for multi-number routing.

WhatsApp Product Catalog

Commerce API

Send interactive Single Product Messages (SPM), Multi-Product Messages (MPM), or full Storefront Catalog Messages linked directly to your Meta Commerce Manager catalog. Requires a plan with allow_catalog enabled and a connected Meta Catalog ID.

GET/api/v1/catalog/status

Verify whether the active workspace subscription includes catalog access and inspect the connected Meta Commerce Catalog ID.

Lang:

curl -X GET "/api/v1/catalog/status" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

POST/api/v1/catalog/send-single-product

Send a Single Product Message (SPM). WhatsApp automatically renders the product's image, title, price, and description directly from your Meta Commerce Catalog with a "View" button.

Lang:

curl -X POST "/api/v1/catalog/send-single-product" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "919876543210",
  "product_retailer_id": "SKU-SHOE-001",
  "body_text": "Hi John, the Nike Air Max you viewed is back in stock in your size!",
  "footer_text": "Free returns within 30 days",
  "whatsapp_number_key": "AK7MXP2RBNCQ"
}'

Field	Type	Required	Description
`to`	string	Required	Customer phone number with country code without plus sign (e.g. "919876543210").
`product_retailer_id`	string	Required	The unique Content ID / SKU of the product configured in your Meta Commerce Manager catalog (alias: "sku").
`body_text`	string	Optional	Optional introductory message text above the product card.
`footer_text`	string	Optional	Optional small footer text at the bottom of the card.
`whatsapp_number_key`	string	Optional	Optional 12-char identifier from Developer Settings for multi-number routing.

POST/api/v1/catalog/send-multi-product

Send a Multi-Product Message (MPM) containing up to 30 items grouped into up to 10 sections. Customers can add items to an in-app cart and submit an order directly to your business.

Lang:

curl -X POST "/api/v1/catalog/send-multi-product" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "919876543210",
  "header_text": "Autumn Collection 2026",
  "body_text": "Explore our bestselling footwear and accessories handpicked for you.",
  "footer_text": "Tap View items to browse and checkout",
  "sections": [
    {
      "title": "Footwear",
      "product_items": [
        {
          "product_retailer_id": "SKU-SHOE-001"
        },
        {
          "product_retailer_id": "SKU-SHOE-002"
        }
      ]
    },
    {
      "title": "Accessories",
      "product_items": [
        {
          "product_retailer_id": "SKU-ACC-010"
        }
      ]
    }
  ],
  "whatsapp_number_key": "AK7MXP2RBNCQ"
}'

Field	Type	Required	Description
`to`	string	Required	Customer phone number with country code without plus sign (e.g. "919876543210").
`header_text`	string	Required	Header text shown at top of the message (max 60 chars, e.g. "Featured Products").
`body_text`	string	Required	Main promotional copy or explanation (max 1024 chars).
`sections`	object[]	Required	Array of sections (max 10 sections, max 30 products total across all sections). Each section requires { title: string, product_items: [{ product_retailer_id: string }] }.
`footer_text`	string	Optional	Optional footer text (max 60 chars).
`whatsapp_number_key`	string	Optional	Optional 12-char identifier from Developer Settings for multi-number routing.

POST/api/v1/catalog/send-catalog

Send a full Storefront Catalog Message with a prominent "View catalog" CTA button. Clicking opens your complete Meta Commerce store inside WhatsApp.

Lang:

curl -X POST "/api/v1/catalog/send-catalog" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "919876543210",
  "body_text": "Welcome to our store! Tap below to browse our complete product catalog and place an order directly inside WhatsApp.",
  "footer_text": "Open 24/7 with instant dispatch",
  "thumbnail_product_retailer_id": "SKU-SHOE-001",
  "whatsapp_number_key": "AK7MXP2RBNCQ"
}'

Field	Type	Required	Description
`to`	string	Required	Customer phone number with country code without plus sign (e.g. "919876543210").
`body_text`	string	Required	Main message text inviting the customer to browse your catalog.
`thumbnail_product_retailer_id`	string	Optional	Optional product SKU whose image will be used as the preview thumbnail on the catalog message.
`footer_text`	string	Optional	Optional footer text.
`whatsapp_number_key`	string	Optional	Optional 12-char identifier from Developer Settings for multi-number routing.

Payment Requests (WhatsApp & Razorpay)

In-App & Links

Request payments directly from your customers via WhatsApp using either Native In-App Checkout (Meta WhatsApp Payments) or Razorpay Payment Links with interactive Pay CTA buttons.

POST/api/v1/messages/payment

Send an in-app WhatsApp payment order card or a Razorpay payment link button to any customer.

Lang:

curl -X POST "/api/v1/messages/payment" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "919876543210",
  "amount": 499,
  "currency": "INR",
  "description": "Order #ORD-1001 Payment",
  "reference_id": "ORD-1001",
  "payment_type": "whatsapp_native",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "items": [
    {
      "name": "Pro Plan Subscription",
      "amount": 499,
      "quantity": 1
    }
  ]
}'

Request Parameters

Field	Type	Required	Description
`to`	string	Required	Customer phone number with country code without plus sign (e.g. "919876543210").
`amount`	number	Required	Total payable amount in INR (numeric, e.g. 499.00).
`payment_type`	string	Optional	Payment flow: "whatsapp_native" (in-app order_details) or "razorpay_link" (checkout link button). Defaults to "whatsapp_native".
`reference_id`	string	Optional	Your unique Order / Invoice reference ID (e.g. "ORD-1001"). Auto-generated if omitted.
`description`	string	Optional	Brief summary shown on customer bill / checkout prompt.
`items`	object[]	Optional	Array of line items with { name, amount, quantity }.
`whatsapp_number_key`	string	Optional	Unique 12-char key for multi-number routing from Developer Settings.

GET/api/v1/payments/requests/:reference_id

Fetch the live status of any payment request using your reference_id or internal database ID.

Lang:

curl -X GET "/api/v1/payments/requests/ORD-1001" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

POST/api/v1/payments/requests/:reference_id/cancel

Cancel an unpaid payment request.

Lang:

curl -X POST "/api/v1/payments/requests/ORD-1001/cancel" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json"

Outbound Webhooks (Real-Time Events)

Real-Time HTTP POST

Configure your server endpoint in Developer Settings to receive instant HTTP POST callbacks whenever a payment is completed, failed, or expired on WhatsApp.

Webhook Headers Sent by SocialAPI

Content-Type: application/json
X-Webhook-Signature: sha256=<HMAC_SHA256_HEX> (Computed using your Webhook Secret).
X-Webhook-Event: The event name (e.g. payment.received, payment.expired).
User-Agent: SocialAPI-Webhook/1.0

Sample Webhook Payload (payment.received)

{
  "event": "payment.received",
  "timestamp": "2026-08-22T01:00:00+05:30",
  "data": {
    "id": 14,
    "reference_id": "ORD-1001",
    "customer_phone": "919876543210",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "amount": 499.00,
    "currency": "INR",
    "gateway_fee": 11.78,
    "platform_fee": 0.00,
    "net_amount": 487.22,
    "status": "paid",
    "payment_type": "whatsapp_native",
    "razorpay_payment_id": "pay_Ox8291038",
    "paid_at": "2026-08-22 01:00:00",
    "description": "Order #ORD-1001 Payment"
  }
}

Verifying Webhook Signatures on Your Server

HMAC SHA256

Every outgoing webhook includes an X-Webhook-Signature header. Use your secret key to verify the payload integrity before processing events.

Lang:

# Test local webhook endpoint with mock signature
curl -X POST "http://localhost:3000/api/payment-webhook" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=<MOCK_HMAC_SHA256>" \
  -d '{"event":"payment.received","data":{"reference_id":"ORD-1001"}}'

Contacts

No Import Limit: You can store and import an unlimited number of contacts via API. There is no cap on contact storage. The contact_limit field in your subscription profile refers exclusively to your plan's Monthly Unique Contacts (MUC) — the number of unique recipients you can send messages to per billing cycle.

POST/api/v1/contacts/import

Import or update contacts in bulk. Requires a JSON array of contact objects. No limit applies to how many contacts you can import.

Lang:

curl -X POST "/api/v1/contacts/import" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "contacts": [
    {
      "country_code": "91",
      "phone": "9876543210",
      "first_name": "John",
      "last_name": "Doe",
      "tags": [
        "lead",
        "vip"
      ]
    },
    {
      "phone": "15550001234"
    }
  ]
}'

Workspace & Profile

GET/api/profile

Retrieve your current workspace profile, business details, and active subscription quota metrics.

Lang:

curl -X GET "/api/profile" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

ℹUnderstanding contact_limit in the Profile API

Billing Context

When you call /api/profile, the response includes a subscription object with:

Field	Meaning & Enforcement
`contact_limit`	The maximum number of unique recipients you can send messages to in the current billing cycle (Monthly Unique Contacts / MUC). Not a storage limit.
`contact_count`	The total number of stored contacts in your workspace (informational only, never throttled or capped).
`is_unlimited_contacts`	`true` if your workspace subscription has no MUC restriction (Agency and Enterprise plans).

If a campaign or message send would push your unique recipient count above contact_limit, the API returns HTTP 400 with an error message and automatically notifies your account email to upgrade.