WhatsApp Business API

The WhatsApp Business API sends an approved WhatsApp template to one recipient per request, from your own code. Use it for the messages your system already knows when to send: order and shipping updates, appointment reminders, payment confirmations, renewal notices.

Every request goes through an API campaign that you create once in the Agentive Chat dashboard. The campaign fixes the template, the sending number and which variables come from the request, so your code only sends the values that change. Broadcasts to a list and campaigns that fire on Agentive events stay in the dashboard; this API is for sends that your own system triggers.

If your Agentive Voice account is connected, call events become triggers too, so a missed call can send a template with no code at all. See When Agentive Voice is connected.

Agentive ships two API families: the Voice APIs (Voice Broadcast, AI Voice Agent, Voice OTP and telephony webhooks) and the WhatsApp Business API. They share a brand, a dashboard account and a set of habits, but they are separate products and they do not agree on everything. This section is the one place that says what is common and, where they differ, exactly how.

https://app.agentive.co.in/api/v1

Every path on this page is relative to this base. HTTPS only, JSON in and JSON out. This is the Agentive Chat app; the voice APIs use a different base, listed on their own pages.

Each API campaign has its own token, prefixed agcamp_. It is shown once when the campaign goes live and can be rotated at any time from the campaign page (Agent > WhatsApp > Campaigns > your campaign). A token only sends for the campaign it belongs to, so a leaked token can never reach another template or number.

Send it on every request in the Authorization header:

curl https://app.agentive.co.in/api/v1/whatsapp/campaigns/cmf3k9d2a0001x7q2m4n8p1r6/send \
  -H "Authorization: Bearer agcamp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+919876543210", "templateParams": ["Asha"] }'

Tokens are compared in constant time. A missing or wrong token returns HTTP 401 with one of two codes:

{
  "error": "Send the campaign token as Authorization: Bearer <token>.",
  "code": "missing_token"
}

Every response is JSON. A send that was accepted returns HTTP 200 with success: true:

{
  "success": true,
  "duplicate": false,
  "status": "accepted",
  "messageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNkY3QjE4RkY0RjA2NDU2QjAxAA==",
  "deliveryId": "cmf3kd8y10004x7q2h1k3v9pz",
  "contactId": "cmf1a2b3c0009x7q2d4e5f6g7",
  "warnings": []
}

Anything else returns the matching HTTP status (400, 401, 404, 409, 429 or 502) and one error shape:

{
  "error": "templateParams has 2 values but the template body needs 3.",
  "code": "missing_template_values",
  "details": { "missing": ["body_3"] }
}

Every error carries a stable code. The table lists all of them with what to do. Most 4xx codes are yours to fix before resending; the 429 codes are timing; the 502 codes come from WhatsApp and are safe to retry with the same externalId.

{
  "error": "(#131026) Message undeliverable",
  "code": "meta_rejected",
  "details": {
    "meta": { "code": 131026, "message": "Message undeliverable" }
  }
}

{
  "error": "Quiet hours are on. Sending resumes at 6 Sep 2026, 9:00 am IST.",
  "code": "quiet_hours",
  "details": { "retryAfter": "2026-09-06T09:00:00+05:30" }
}

Requests are limited per token to 300 requests per minute over a sliding window. One campaign's traffic never throttles another. Over the limit you receive HTTP 429 with rate_limited and a Retry-After header in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "Too many requests for this token. Retry after 12 seconds.",
  "code": "rate_limited"
}

Two more 429 codes are about the recipient rather than your request rate, and they are not retried the same way:

• frequency_cap: WhatsApp limits how many marketing messages one person can receive in 24 hours. The delivery is recorded as skipped, nothing was sent, and there is nothing to retry today.
• quiet_hours: the campaign has quiet hours and the request arrived inside them. Nothing was sent. Queue it until details.retryAfter (IST) and resend with the same externalId.

One endpoint sends a message. The older trigger URL still works and shares the same handler, so both accept the same body and return the same responses.

curl https://app.agentive.co.in/api/v1/whatsapp/campaigns/cmf3k9d2a0001x7q2m4n8p1r6/send \
  -H "Authorization: Bearer agcamp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "name": "Asha Verma",
    "templateParams": ["Asha", "ORD-1142", "Friday, 12 September"],
    "buttons": { "0": "orders/ORD-1142" },
    "tags": ["customer", "shipped"],
    "attributes": { "city": "Pune", "orderValue": "2499" },
    "source": "shopify",
    "externalId": "order-1142-shipped",
    "callbackData": "order=ORD-1142"
  }'

{
  "success": true,
  "duplicate": false,
  "status": "accepted",
  "messageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNkY3QjE4RkY0RjA2NDU2QjAxAA==",
  "deliveryId": "cmf3kd8y10004x7q2h1k3v9pz",
  "contactId": "cmf1a2b3c0009x7q2d4e5f6g7",
  "warnings": []
}

{
  "success": true,
  "duplicate": true,
  "status": "delivered",
  "messageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNkY3QjE4RkY0RjA2NDU2QjAxAA==",
  "deliveryId": "cmf3kd8y10004x7q2h1k3v9pz",
  "contactId": "cmf1a2b3c0009x7q2d4e5f6g7",
  "warnings": []
}

curl https://app.agentive.co.in/api/chatbots/cmk2p4x1a0000x7q2b9c3d4e5/whatsapp/campaigns/cmf3k9d2a0001x7q2m4n8p1r6/trigger \
  -H "Authorization: Bearer agcamp_..." \
  -H "Content-Type: application/json" \
  -d '{ "destination": "9876543210", "userName": "Asha Verma", "templateParams": ["Asha", "ORD-1142", "Friday, 12 September"] }'

A WhatsApp template has numbered placeholders, {{1}} to {{n}}, in its body, sometimes in its header, and in any dynamic button. When you create the API campaign you decide, per variable, whether it has a fixed value or comes from the request. Only the request-mapped ones need to be sent.

Header:  DOCUMENT
Body:    Hi {{1}}, your order {{2}} has shipped and should reach you by {{3}}.
Footer:  Reply STOP to opt out.
Buttons: [0] URL "Track order"  https://shop.example.in/{{1}}
         [1] QUICK_REPLY "Need help?"

The request that fills every variable of that template:

{
  "to": "+919876543210",
  "templateParams": ["Asha", "ORD-1142", "Friday, 12 September"],
  "media": {
    "url": "https://cdn.example.in/invoices/ORD-1142.pdf",
    "filename": "Invoice ORD-1142.pdf"
  },
  "buttons": { "0": "orders/ORD-1142", "1": "HELP_ORD-1142" }
}

{
  "to": "+919876543210",
  "headerText": "Order ORD-1142",
  "templateParams": ["Asha", "Friday, 12 September"]
}

// Keyed by button index. The template decides what each value means.
{ "buttons": { "0": "orders/ORD-1142", "1": "HELP_ORD-1142" } }

// The same request in positional form.
{ "buttons": ["orders/ORD-1142", "HELP_ORD-1142"] }

// A URL button accepts either the dynamic suffix or the full URL.
{ "buttons": { "0": "https://shop.example.in/orders/ORD-1142" } }

// A COPY_CODE button takes the coupon code the recipient copies.
{ "buttons": { "0": "DIWALI20" } }

{
  "to": "+919876543210",
  "values": {
    "body_1": "Asha",
    "body_2": "ORD-1142",
    "body_3": "Friday, 12 September",
    "header_1": "Order ORD-1142",
    "button_0_url_1": "orders/ORD-1142"
  }
}

A template with an image, video or document header needs a file on every send. Give WhatsApp a public https URL it can fetch at send time, or the id of a file already uploaded to your number.

// Image or video header: a public https URL.
{ "media": { "url": "https://cdn.example.in/offers/diwali-2026.jpg" } }

// Document header: add the filename the recipient sees.
{ "media": { "url": "https://cdn.example.in/invoices/ORD-1142.pdf", "filename": "Invoice ORD-1142.pdf" } }

// A media id you already uploaded to your WhatsApp number.
{ "media": { "id": "1234567890123456" } }

• The URL must be https, at most 2048 characters, and reachable without a login. A signed URL that stays valid for 10 minutes is fine; the file is fetched once, when the message is sent.
• The response Content-Type must match the file (for example application/pdf); a mismatched type is rejected by WhatsApp as meta_rejected.
• If you saved a default file on the campaign in the dashboard, omit media and that file is used. A media-header template with neither is a 400 media_required.
• The legacy key values.header_media_url still works and means the same as media.url.

Every send creates or matches a contact by phone number, so the request can enrich it at the same time. Tags and attributes are filterable in the dashboard and usable as audience filters for broadcasts and retargeting.

// Request
{
  "tags": ["Customer", "shipped", "customer"],
  "attributes": { "city": "Pune", "orderValue": 2499, "Last Order": "ORD-1142", "notes": null }
}

// Stored on the contact
{
  "tags": ["Customer", "shipped"],
  "attributes": { "city": "Pune", "order_value": "2499", "last_order": "ORD-1142" }
}

name and email fill the contact record the same way, and source is recorded as the contact's first source when the contact is new.

Set externalId (or the Idempotency-Key header) on every send that a retry could repeat. Pick it from your own system: the object plus the event, such as order-1142-shipped. Keys are scoped to the campaign and may be up to 160 characters.

• The same externalId never sends twice. A repeat returns HTTP 200 with duplicate: true and the earlier delivery's current status, whether that is accepted, delivered or failed.
• A send that WhatsApp rejects (meta_rejected or send_failed) releases the key. Fix the problem and retry with the same externalId; the retry sends fresh and the failed attempt stays in the history.
• A request rejected before the send (validation, missing values, wrong token, quiet hours) never consumes the key.
• Without an externalId, every request sends a new message. Network retries then mean duplicate messages to the customer.

{
  "success": true,
  "duplicate": true,
  "status": "delivered",
  "messageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNkY3QjE4RkY0RjA2NDU2QjAxAA==",
  "deliveryId": "cmf3kd8y10004x7q2h1k3v9pz",
  "contactId": "cmf1a2b3c0009x7q2d4e5f6g7",
  "warnings": []
}

Delivery status arrives on a webhook instead of polling. Add an endpoint under Agent > Webhooks, subscribe it to whatsapp.message.status, and copy its signing secret. One event is delivered for each status change of a message: sent, delivered, read, replied, clicked, failed.

Correlate on externalId, callbackData, or messageId from the send response. Statuses can arrive out of order (read before delivered when a phone comes back online), so treat the furthest state you have seen as current rather than the latest event.

{
  "id": "evt_5f1c9a2b7d3e4f60a1b2c3d4",
  "event": "whatsapp.message.status",
  "apiVersion": "2026-05-08",
  "chatbotId": "cmk2p4x1a0000x7q2b9c3d4e5",
  "chatbot": {
    "id": "cmk2p4x1a0000x7q2b9c3d4e5",
    "name": "Orders assistant",
    "orgId": "cmk2p3w9z0000x7q2a1b2c3d4"
  },
  "timestamp": "2026-09-05T10:42:17.913Z",
  "data": {
    "messageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNkY3QjE4RkY0RjA2NDU2QjAxAA==",
    "deliveryId": "cmf3kd8y10004x7q2h1k3v9pz",
    "campaignId": "cmf3k9d2a0001x7q2m4n8p1r6",
    "campaignName": "Order shipped (API)",
    "campaignType": "api",
    "to": "919876543210",
    "status": "delivered",
    "externalId": "order-1142-shipped",
    "callbackData": "order=ORD-1142",
    "timestamp": "2026-09-05T10:42:17.913Z",
    "pricing": { "category": "utility", "billable": true }
  }
}

"data": {
  "messageId": null,
  "deliveryId": "cmf3kd8y10004x7q2h1k3v9pz",
  "campaignId": "cmf3k9d2a0001x7q2m4n8p1r6",
  "campaignName": "Order shipped (API)",
  "campaignType": "api",
  "to": "919876543210",
  "status": "failed",
  "externalId": "order-1142-shipped",
  "callbackData": "order=ORD-1142",
  "timestamp": "2026-09-05T10:42:19.204Z",
  "error": { "code": 131026, "title": "Message undeliverable" }
}

X-Agentive-Signature: 4f1d2c9b8a7e6f5d4c3b2a1908f7e6d5c4b3a291807f6e5d4c3b2a19080706e9

import express from "express";
import crypto from "node:crypto";

const app = express();

// Read the RAW body: the signature covers the exact bytes we sent.
app.post(
  "/webhooks/agentive",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const secret = process.env.AGENTIVE_WEBHOOK_SECRET;
    if (!secret) return res.status(500).send("signing secret not set"); // never verify with an empty key
    const given = Buffer.from(req.header("X-Agentive-Signature") ?? "", "utf8");
    const expected = Buffer.from(
      crypto.createHmac("sha256", secret).update(req.body).digest("hex"),
      "utf8"
    );

    // Compare byte lengths first: timingSafeEqual throws on unequal lengths.
    const ok =
      given.length === expected.length && crypto.timingSafeEqual(given, expected);
    if (!ok) return res.status(401).send("bad signature");

    const evt = JSON.parse(req.body.toString("utf8"));

    // Deliveries retry, so skip an evt.id you have already processed.
    if (evt.event === "whatsapp.message.status") {
      const { status, externalId, callbackData, error } = evt.data;
      console.log(externalId, status, callbackData, error?.title);
    }

    res.sendStatus(200);
  }
);

app.listen(3000);

From an approved template to a delivered message.

1. 1
   Create an API campaign

   In the Agentive Chat dashboard open your agent, then WhatsApp > Campaigns > New campaign > API campaign. Pick an approved template, choose which variables come from the request (and fix the rest), and go live.
2. 2
   Copy the token

   The campaign page shows the token once. Store it as an environment variable on your server, for example AGENTIVE_CAMPAIGN_TOKEN, together with the campaign id from the same page. Lost it? Rotate from the campaign page and copy the new one.
3. 3
   Send your first message

   Replace the placeholders and send to your own number. Send one templateParams entry per request-mapped body variable.

   cURL

   Copy

   curl https://app.agentive.co.in/api/v1/whatsapp/campaigns/<campaignId>/send \
     -H "Authorization: Bearer <agcamp_token>" \
     -H "Content-Type: application/json" \
     -d '{
       "to": "+91XXXXXXXXXX",
       "templateParams": ["Asha"],
       "externalId": "first-test-1"
     }'

4. 4
   Verify delivery

   The response carries status: "accepted" and a messageId. Open the campaign's Deliveries tab to watch it move through sent, delivered and read, or subscribe a webhook to whatsapp.message.status to receive the same states in your own system.

The request is deliberately close to what the popular Indian WhatsApp APIs accept, so most integrations move by changing the URL, the auth header and a few field names. The aliases destination, userName and idempotencyKey are accepted as is.

Connecting your Agentive Voice account to Agentive Chat adds call events as triggers for Ongoing WhatsApp campaigns, so a missed call, a finished call, a voicemail or a callback request can send an approved template on its own. Everything is set up from the Voice panel, and none of it needs code.

The other Agentive references, on the Voice app.