Skip to content

WhatsApp Business API Guide

WhatsApp on Azmarq is the WhatsApp Business channel: WhatsApp App (messaging), Commerce, WhatsApp Flows, and CTWA (Click-to-WhatsApp Ads). Send from the portal or from your systems with an API key.

There are two different “flows” in this product. Do not mix them:

  1. WhatsApp Flows — Meta interactive Flows (forms, screens, flow_json).
  2. Automation / WorkFlow — in-app chatbot builder (keywords, API steps, catalog steps) under WhatsApp App.

What WhatsApp App is

Customers can:

  1. Send template and session messages from the portal (Quick Send, Direct Send, bulk file).
  2. Send the same channel from their own systems with an API key.
  3. Manage WABA numbers, templates, media, groups, opt-in, blocklist, DLR webhooks, and reports.
  4. Sell with WhatsApp Commerce (catalog, products, orders, payments).
  5. Build Meta WhatsApp Flows and attach them to templates / sends.
  6. Run Click-to-WhatsApp Ads (CTWA) from Meta Ads, then chat those leads in Team Inbox.
  7. Reply in Team Inbox (agent chat).

Wallet credits are deducted per conversation / message according to the assigned WhatsApp gateway. Blocked numbers are skipped.

Sibling portal menus: WhatsApp App, Commerce, WhatsApp Flows, CTWA Manager, and Team Inbox.

Get ready before sending

SetupWhereWhy
Wallet balanceUser walletWhatsApp is billed from credits
Connected WhatsApp numberWhatsApp App → Add Numbersfrom on the API is this business number
WABA linked to that numberSame screenTemplates and Flows belong to a WABA
Approved templateWhatsApp App → Utility → Manage TemplateRequired for business-initiated (template) sends
Gateway / routeAssigned to the accountOptional gatewayId on API
API keySystem → Developer → API KeyHeader apikey
Media (if header is image/video/document)Utility → Manage WhatsApp MediaPass mediaId or mediaUrl

API keys can have an IP allowlist and priority. Inactive users or keys are rejected.

WABA and numbers

A WhatsApp Business Account (WABA) is the Meta container for your business on WhatsApp. These all belong to a WABA:

  • Phone numbers (the from value on send)
  • Message templates
  • WhatsApp Flows
  • Product catalogs (Commerce)

Add Numbers connects a business number to that WABA and to this portal. Until the number is connected and quality is usable, you cannot send. Display name, business profile, and official business account status are managed in Meta / WhatsApp Manager; this portal lists the connected number and syncs templates and Flows from that WABA.

One account can have more than one number. Always pass the number you intend as from.

Customers must opt in before you message them (keyword, website checkbox, click-to-WhatsApp, or another Meta-allowed source). Use Opt-in management for keyword opt-in / opt-out. Sending to people who never opted in is against WhatsApp policy and can restrict the number.

What a WhatsApp template is

A WhatsApp template is a pre-approved message format. Meta reviews the wording, placeholders, buttons, and category before you can send it.

You cannot open a new chat with free-form text. If the customer has not messaged you in the last 24 hours, the only outbound message allowed is an approved template.

Templates are created per WABA + language. The name you send as templateName must match an Approved template on that WABA. Create or sync them under WhatsApp App → Utility → Manage Template. HTTP create/list: Create templates.

Typical parts of a template:

PartWhat it is
NameStable id you pass as templateName (not the on-screen title)
LanguageLocale Meta approved (for example en, en_US, hi)
Categoryauthentication, utility, or marketing
HeaderOptional text, image, video, document, or location
BodyMain text. Variables are numbered placeholders such as {'{{1}}'}
FooterOptional short static line
ButtonsQuick reply, visit website, call, copy code, catalog, or Flow

Status is independent of Azmarq wallet credits. Pending / Rejected / Paused templates cannot be used on send.

Template categories

Pick the category that matches the real purpose. Wrong category is the most common rejection. Meta can recategorize or pause a template after approval.

CategoryWhen to useExamplesWhen not to use
AuthenticationA one-time code that verifies a personOTP, login, 2FAOffers, “your order is shipped”, newsletters
UtilityA follow-up on something the user already started or ownsOrder shipped, ticket update, appointment reminder, payment receiptFirst-time promo, win-back, “check our new collection”
MarketingPromotions, invitations, or any outreach that is not a specific transaction updateDiscounts, catalogs, re-engagement, event invitesOTPs. If it is promotional, it is marketing even if you also mention an order

Authentication templates have extra Meta rules (OTP format, expiration language, limited buttons). Use the Authentication template screen when that is the use case. Pass otp on send when the template expects it.

Marketing vs utility is about intent, not tone. “Your order #123 shipped” is utility. “Your order shipped — here’s 20% off the next one” is marketing.

Conversation charges follow Meta’s category rules. Opening a marketing conversation is billed as marketing; utility and authentication have their own rates. Wallet credits here follow the assigned WhatsApp gateway.

How templates work

  1. Compose the template in Manage Template (or start from Template library). Keep variables only where the value will change. Body placeholders are {'{{1}}'}, {'{{2}}'}, in order.
  2. Submit to Meta. Status becomes Pending.
  3. Wait for Approved. Rejected templates include a Meta reason (category, wording, variable misuse, missing sample values). Fix and resubmit; do not send the rejected name.
  4. Send from Quick Send / Direct Send / bulk file, or POST /v1/whatsapp with type: template, templateName, language, and components.
  5. Fill variables in components.body.params in the same order as {'{{1}}'}, {'{{2}}'}. Header media uses mediaId or mediaUrl when the header is not text.
  6. Meta may later pause a template if quality drops (blocks, reports). Paused names fail on send until Meta restores them. Check Template insights and WhatsApp Manager quality.

Sample values you submit at create time are for Meta review only. Live sends must pass real components values.

Buttons:

  • Quick reply — user taps a preset reply; that opens or continues the session window.
  • URL — can include a variable suffix if the template defined one.
  • Phone — calls a fixed number.
  • Flow — opens a WhatsApp Flow.
  • Catalog / MPM — product cards from Commerce.

Do not change placeholder order on an approved template without creating a new template. Edits often require Meta to review again.

Session window

WhatsApp splits traffic into template messages and session messages.

TemplateSession (text, image, interactive, …)
When you may sendAnytime (user opted in, template Approved)Only while the 24-hour customer-care window is open
Who startsBusinessCustomer last messaged you (or tapped a reply that opens the window)
WindowNot requiredStarts when the user messages you; lasts 24 hours
Typical useOTP, alerts, campaignsAgent replies in Team Inbox, free-form follow-up

The window is per customer, per business number. A template send does not always open a session window for free-form follow-up — user reply does. If the window is closed, session type values fail; send an approved template instead.

Team Inbox is the agent UI for open sessions. Automation / WorkFlow can reply inside the window. Neither replaces templates for business-initiated outreach.

WhatsApp App

Portal prefix: /whatsapp-app/...

Send campaigns

ToolWhat you doWhen to use
Quick SendCompose a campaign: audience, number, approved template, scheduleBroadcasts and marketing / utility / auth templates
Direct SendStepper: recipients → message → campaign → previewGuided one-off send
Bulk file sendUpload CSV/Excel mapped to numbers (and optional agent / variables)Large campaigns

Audience sources (compose)

  • Manual numbers
  • Saved contacts: groups, categories, tags, CDP segments / sources / tags
  • File upload
  • Optional exclude blocklist / include duplicates
  • Optional schedule, split send (dateTime, isSplit, batchSplit, timeSplit)
  • Optional fallback to SMS or RCS. Create the rule under Fallback Routing, then Enable Fallback on compose.
  • Optional attach a Flow (flowId, flowToken) on compose/bulk

Numbers and account

ToolWhat it is
Add NumbersConnect / list WhatsApp Business numbers, WABA, Meta sync
WA SettingsPer-number settings
Payment configurationWhatsApp Pay / payment gateway for commerce
Subscription dashboardNumber subscription / billing

Templates and media

Template categories are explained above: authentication, marketing, utility.

ToolWhat it is
Manage templatesList, sync from Meta, status, category
Add / edit templateBuild components (header, body, buttons, carousel)
Authentication templateOTP / auth templates
Catalogue templateProduct catalog templates
Template libraryBrowse Meta’s message template library
Template insightsPerformance of templates
Predefined messagesCanned replies for inbox
Manage WhatsApp mediaImages / video / audio / documents for headers

Full HTTP create/list payloads: Create templates.

Groups

ToolWhat it is
Groups listWhatsApp Groups on the business number
Create groupSubject, description, join approval
Group detailsParticipants, invite link, join requests, send group message

HTTP group operations: WhatsApp Groups.

Utilities

ToolWhat it is
Opt-in managementOpt-in / opt-out keyword messages
WhatsApp blocklistDo-not-send numbers (manual + bulk)
DLR / webhook configPush delivery / inbound events to your URL (name, endPoint, headers, wabaId, fromMobileNumber, optional inbound + template webhook URLs)

Inbox and automation

ToolWhat it is
RepliesInbound conversation view
Team Inbox (/team-inbox/chat)Agent chat: assign, reply, session, unread. Full guide: Team Inbox
Automation list / builder / analyticsWorkFlow chatbot (keywords, API calls, catalog steps). This is not Meta Flows. Full guide: Automations

Reports

ReportUse
Message reportCampaign-level sends
Number reportPer-recipient status for a campaign
Conversation / message logsSession-level logs
Inbound messagesIncoming user messages
Clicker reportLink clicks
Flow reportAutomation / workflow message report
Order logsCommerce order messages
Payment detailsPayments against a campaign
Report downloadExport

WhatsApp Commerce

Portal prefix: /commerce/...

WhatsApp Commerce is selling from a Meta product catalog attached to the WABA. Customers browse products, add to cart, and place an order inside WhatsApp. You do not need a separate /v1/commerce send API — catalog templates and session catalog messages still go through WhatsApp send.

When to use it: you already have SKUs to show on WhatsApp (retail, restaurants, appointments-with-add-ons). When not to use it: OTP or alert traffic; use a normal template.

How it works:

  1. Connect or create a catalog on the WABA (Commerce → Settings).
  2. Add or sync products (name, price, image, availability). Use bulk add for large catalogs.
  3. Optionally set cart / catalog visibility.
  4. Send a catalogue template or catalog interactive message from WhatsApp App.
  5. Customer places an order in WhatsApp. See Orders, Order logs, and Payment details.
  6. Collect payment if Payment configuration is set on the number (WhatsApp Pay / connected gateway).

Catalog data lives on Meta. Keep product status in sync; paused or deleted items cannot be ordered.

ScreenWhat you do
SettingsConnect or create catalog, cart visibility, catalog visibility, connect from Meta
CatalogCatalog overview
ProductsAdd / list / sync products; bulk add; batch status
Product detailSingle product
CategoriesProduct categories
OrdersWhatsApp order reports

Related in WhatsApp App: catalogue templates, payment configuration on the number, order logs and payment details in reports.

Commerce is portal-first. There is no public /v1/commerce HTTP API. Customer HTTP send still uses /v1/whatsapp templates (including catalog templates).

WhatsApp Flows

Portal prefix: /whatsapp-flows/...

WhatsApp Flows are Meta’s in-chat forms: multiple screens the customer completes without leaving WhatsApp. Typical uses: appointment booking, lead capture, surveys, KYC-style fields, checkout helpers.

A Flow is not a website, not a PDF, and not the in-app chatbot. The UI is defined as flow_json (screens, fields, routing) and runs inside the WhatsApp client.

When to use a Flow

Use a FlowUse something else
You need structured fields (date, dropdown, ID number)You only need to send an alert — use a template
The user should finish a form in WhatsAppYou need keyword bots / API lookups — use WorkFlow
You will attach the form to a template button or sendYou are chatting ad-hoc in Team Inbox

How a Flow works

  1. Create a Flow on the WABA: name, categories, flow_json, optional endpoint_uri and description.
  2. Preview to check screens. Draft Flows cannot be sent to customers.
  3. Publish to Meta. Only published Flows can be attached to a template or campaign.
  4. Attach it:
    • as a Flow button on a WhatsApp template, or
    • from Quick Send / bulk with flowId and flowToken.
  5. The customer opens the Flow, fills screens, and submits. You see results on Flow dashboard (and on your endpoint_uri if you set one).

endpoint_uri is optional. Use it when a screen must load live data from your server (available slots, order details). Static forms do not need an endpoint.

Create fields: name, categories, flow_json, wabaId, optional endpoint_uri, description.

ScreenWhat you do
Flows listAll Flows on the WABA
Create FlowName, categories, flow_json, optional endpoint_uri, description
Edit FlowUpdate JSON / metadata
PublishMake the Flow available on Meta
Flow dashboardSubmissions / usage for a Flow
PreviewPreview a Flow

Unpublished, rejected, or deprecated Flows cannot be sent. After you edit flow_json, publish again.

WorkFlow automation

WorkFlow (WhatsApp App → Automation) is Azmarq’s chatbot builder. It is not Meta Flows. The full product guide is Automations (WhatsApp and RCS).

Use it to reply automatically when a customer messages you: keywords, menus, API calls, catalog steps, handoff to Team Inbox. It runs inside the session window (and on inbound keywords). It cannot replace an approved template for business-initiated broadcasts.

WhatsApp FlowsWorkFlow automation
Whose productMetaThis portal
What the user seesNative multi-screen formChat messages / buttons you script
Setupflow_json + publishAutomation list / builder
Typical triggerTemplate Flow button or send flowIdInbound message, keyword
MenuWhatsApp FlowsWhatsApp App → Automation

CTWA

Portal prefix: /ctwa-manager/...

CTWA is Click-to-WhatsApp Ads (not CWTA). It is a Meta Ads campaign whose call-to-action opens a WhatsApp chat with your business number. The customer starts the conversation; you then reply in Team Inbox (or WorkFlow).

CTWA is not a send API. You do not POST /v1/whatsapp to “fire the ad”. You bind Ads credentials in this portal, create/pause campaigns here (or in Meta Ads Manager), and handle the inbound chats.

How it works:

  1. You need a Meta Ad Account, a Facebook Page linked to the WABA / number, and a valid ads token.
  2. Complete Account setup: adAccountId, pageId, adsToken, metaApiVersion.
  3. Create a campaign (engagement, leads, sales, or traffic). Default status is PAUSED until you set ACTIVE.
  4. People who click the ad land in WhatsApp. They appear under Leads and in Team Inbox.
  5. First business replies inside the open session; later outreach still needs a template if the 24-hour window closed.

Identity of those leads is covered on My CDP.

ScreenWhat you do
Account setupBind a WhatsApp number to Meta: adAccountId, pageId, adsToken, metaApiVersion
DashboardAccount / campaign performance
Ads managerList campaigns, ad sets, creatives, ads
Create campaignWizard: campaign → ad set → creative → ad
Ad detailSingle ad performance
LeadsPeople who clicked through to WhatsApp

Campaign objectives: OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC.

Statuses: ACTIVE or PAUSED (default paused).

Ad set: campaign_id, daily_budget, targeting, optional billing / optimization.

CTWA APIs are portal (JWT) tools, not the public apikey send API. Do not call CTWA as $API_BASE_URL/v1/whatsapp endpoints.

Developer setup

  1. Create an API key under System → Developer → API Key. See Authentication.
  2. Optionally restrict the key with an IP allowlist.
  3. Copy $API_BASE_URL from this page — it is white-label / environment specific.
  4. Prefer POST + JSON.
  5. Pass the key as header apikey or apiKey.

from = connected WhatsApp business number.
to = destination mobile number(s).

Send URL for this environment: https://api.azmarq.com/v1/whatsapp.


Send WhatsApp message

GET or POST $API_BASE_URL/v1/whatsapp. Prefer POST + JSON.

Required

  • Name
    apikey
    Type
    string
    Description

    Developer API key (header or body).

  • Name
    from
    Type
    string
    Description

    Connected WhatsApp business number.

  • Name
    to
    Type
    string
    Description

    Destination number.

  • Name
    type
    Type
    string
    Description

    template | interactive | text | video | image | document | audio

  • Name
    templateName
    Type
    string
    Description

    Required when type is template.

Optional

  • Name
    language
    Type
    object
    Description

    Template language object.

  • Name
    components
    Type
    object
    Description

    Template variables. Body placeholders are filled from components.body.params in order.

  • Name
    interactive, text, video, image, audio, document
    Type
    object
    Description

    Session / media payloads when type is not template.

  • Name
    country
    Type
    string
    Description

    Country hint.

  • Name
    gatewayId
    Type
    string
    Description

    Route.

  • Name
    recipient_type
    Type
    string
    Description

    Recipient type.

  • Name
    serviceId
    Type
    string
    Description

    Service.

  • Name
    campaignName
    Type
    string
    Description

    Shown in reports.

  • Name
    mediaId / mediaUrl
    Type
    string
    Description

    Header / media.

  • Name
    advanceLinkOption
    Type
    string
    Description

    Advanced short-link option.

  • Name
    otp
    Type
    string
    Description

    Auth template OTP (max 15 chars).

  • Name
    uuid
    Type
    string
    Description

    Customer correlation id.

  • Name
    meta
    Type
    object
    Description

    Extra metadata object.

components (template variables):

{
  "body": { "params": ["Ravi", "123456"] },
  "header": {},
  "buttons": { "params": ["https://example.com"] },
  "carousel": {
    "cards": [
      {
        "header": {},
        "body": { "params": ["Card 1"] },
        "buttons": { "params": [] }
      }
    ]
  }
}

Header / carousel / interactive samples: Send templates and Interactive messages.

Request

curl --location --request POST 'https://api.azmarq.com/v1/whatsapp' \
--header 'Content-Type: application/json' \
--header 'apikey: YOUR_API_KEY' \
--data-raw '{
  "from": "9198xxxxxxxx",
  "to": "9199xxxxxxxx",
  "type": "template",
  "templateName": "otp_login",
  "language": {
    "code": "en"
  },
  "components": {
    "body": {
      "params": [
        "123456"
      ]
    }
  },
  "campaignName": "otp-login"
}'

GET v2 (template only): GET $API_BASE_URL/v2/whatsapp

Required: from, to, templateName, type=template, apikey.
Optional: language (string), params, headerParam, campaignName, mediaId, mediaUrl.


Customize

POST $API_BASE_URL/v1/whatsapp/customize

One from, up to 100 items in custom. Each item uses the same per-message fields as a single send (to, type, templateName, components, media, otp, uuid, meta, …).

If any item is invalid, the whole batch is rejected. See Errors and the full samples on Customize messages.

Request

curl --location --request POST 'https://api.azmarq.com/v1/whatsapp/customize' \
--header 'Content-Type: application/json' \
--header 'apikey: YOUR_API_KEY' \
--data-raw '{
  "from": "9198xxxxxxxx",
  "campaignName": "order-updates",
  "custom": [
    {
      "to": "9199xxxxxxxx",
      "type": "template",
      "templateName": "order_shipped",
      "components": {
        "body": {
          "params": [
            "1001"
          ]
        }
      }
    },
    {
      "to": "9188xxxxxxxx",
      "type": "template",
      "templateName": "order_shipped",
      "components": {
        "body": {
          "params": [
            "1002"
          ]
        }
      }
    }
  ]
}'

Base64 PDF header

POST $API_BASE_URL/v1/whatsapp/base64 — use when the template header is a PDF sent as base64.

FieldNotes
country_code1–4 digits
fromBusiness number
mobileDestination, 10–15 digits
typeMust be media
templateNameRequired
paramsOptional body params array
headerValues.filenameMust end with .pdf
headerValues.media_base64Base64 PDF

Encrypted recipients

POST $API_BASE_URL/v1/whatsapp/encrypted — same schema as /v1/whatsapp. to is handled as encrypted. Use when the integrator stores numbers encrypted.

Templates and media APIs

All POST $API_BASE_URL/v1/whatsapp/... with apikey.

MethodPathPurpose
POST/v1/whatsapp/createWaTemplateCreate a template on Meta via WABA
POST/v1/whatsapp/updateWaTemplateUpdate; category must be authentication | marketing | utility
POST/v1/whatsapp/deleteWaTemplateDelete by name + wabaId
POST/v1/whatsapp/waTemplateListList
POST/v1/whatsapp/getWaTemplateGet one
POST/v1/whatsapp/generateHeaderHandleUpload file, get Meta header handle
POST/v1/whatsapp/waMediaMultipart field media. Body: apikey, mediaName, mediaType ∈ image | video | audio | document
POST/v1/whatsapp/processFileFile upload helper

Create body:

  • Name
    apikey
    Type
    string
    Description

    Required.

  • Name
    name
    Type
    string
    Description

    Template name.

  • Name
    category
    Type
    string
    Description

    Required. authentication, marketing, or utility.

  • Name
    allow_category_change
    Type
    boolean
    Description

    Optional.

  • Name
    language
    Type
    string
    Description

    Required.

  • Name
    components
    Type
    array
    Description

    Required. Meta component structure.

  • Name
    wabaId
    Type
    string
    Description

    Required.

Component walkthrough: Create templates.

Groups API

All POST $API_BASE_URL/v1/whatsapp/... with apikey.

PathPurposeNotable fields
/createGroupCreatesubject (max 128), description (max 2048), joinApprovalMode: auto_approve | approval_required, plus phoneNumberId or whatsappNumberId
/getGroupsListListsearching, page, limit (max 100)
/syncGroupsFromMetaSyncphoneNumberId
/getGroupByIdGet oneMeta group id
/updateGroupUpdatesubject / description
/deleteGroupDelete
/getGroupInviteLink / /resetGroupInviteLinkInvite link
/addParticipants / /removeParticipantsMembersMeta limit: max 8 removed per request
/sendGroupMessageSend in group
/getGroupJoinRequestsPending joins
/approveGroupJoinRequests / /rejectGroupJoinRequestsModerate

Samples: WhatsApp Groups.

Status and DLR

PathUse
POST /v1/whatsapp/getStatusStatus by apikey + messageRequestId (optional status)
POST /v1/whatsapp/pullDlrStatusPull DLR for messageId
POST /v1/whatsapp/updateDlrStatusBulk DLR update: service, apikey, limit; optional messageId, startDate, endDate, fromStatus, toStatus, errorCode

Configure push DLR in the portal (Utility → DLR config) so Meta delivery events hit your endPoint. Event bodies: WhatsApp webhooks.

Wallet and account

PathUse
POST /v1/user/walletBalanceBalance for apikey
POST /v1/api/whatsapp/getUserDetailsbyApikeyAccount details for the key

Partner connectors

Supported integrations — not the core send API:

PathIntegration
POST /v1/whatsapp/webEngageWebEngage
POST /v1/whatsapp/clevertapCleverTap
POST /v1/whatsapp/moengageMoEngage
GET|POST /v1/moengage/syncWhatsappTemplatesMoEngage template sync
GET /templatesCleverTap template sync
POST /v1/whatsapp/meta/webhookMeta inbound webhook
POST /v1/whatsapp/karix/webhook, /airtel/webhook, /haptik/webhookPartner webhooks
POST /v1/api/wabaMessageAlternate Meta-oriented send

Pages: WebEngage, CleverTap WhatsApp, MoEngage.

How a send behaves

  1. API key is resolved. User must be active.
  2. from must be a connected WhatsApp number on that account.
  3. If type is template, templateName must exist and be approved on the WABA.
  4. Numbers are validated; blocklist numbers are skipped.
  5. Credits are checked on the wallet / gateway price.
  6. The job is queued. Reports later show campaign and per-number status; DLR can be pushed or pulled.
  7. Session types (text, image, …) are for open customer-care windows. Business-initiated chats outside the window must use a template.

The 24-hour window starts when the user messages you. Template messages do not need an open window. Session messages fail if the window is closed.

HTTP 200 with "error": null means the API accepted the job. Handset delivery arrives later as webhook message_status (sent, delivered, read, failed).

Typical errors

SituationWhat it means
Missing / bad keyInvalid API key
User disabledUser deactivated
Unknown fromWhatsApp number not connected
Missing templateName when type=templateTemplate name required
Unapproved / missing templateTemplate not available
Low walletInsufficient credits
Blocked numberNumber skipped (may return success with empty recipients)
custom empty or over 100Batch size 1–100
Base64 header not PDFfilename must end with .pdf
Group without numberProvide phoneNumberId or whatsappNumberId
CTWA not configuredComplete Account setup (adAccountId, pageId, adsToken)

See Errors. Next: Create templates, Send templates, Recipes.

Was this page helpful?