Send WhatsApp messages from your own software

Every request goes to https://pulse.cloudfigma.com over HTTPS, with your API key. Messages go out from your business’s own WhatsApp number, the one Pulse set up for you.

• Get a key. The account owner opens Settings › Developers in Pulse and creates one. It starts cfn_live_ and is shown once, so copy it then. Keep it on your server, never in a web page or an app.
• Send it with every request, in either header below.
• Send JSON with Content-Type: application/json. Answers are JSON too. Phone numbers go in international form, with the country code: +919876543210.

Authorization: Bearer cfn_live_YOUR_KEY

X-API-Key: cfn_live_YOUR_KEY

Every error has the same shape: error is a fixed code for your program to check, and message says what to fix, for a person. Errors lists every code.

{
  "error": "template_not_found",
  "message": "No approved template named \"order_update\" in en. Check the Templates page. It may still be pending Meta's approval."
}

A template is a message Meta approved in advance. It can go at any time, even to a customer who has never written to you. Make templates in Pulse, under Templates; only approved ones can be sent.

POST https://pulse.cloudfigma.com/api/v1/messages

curl -X POST https://pulse.cloudfigma.com/api/v1/messages \
  -H "Authorization: Bearer cfn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "to": "+919876543210",
    "template": "order_update",
    "variables": ["Asha","1001"],
    "client_ref": "order-1001"
  }'

It answers 202: the message is stored and queued for WhatsApp, not yet delivered.

{
  "id": "cm2msg0002",
  "status": "queued",
  "to": "+919876543210",
  "category": "utility",
  "charged": "₹0.00",
  "balance_after": null,
  "client_ref": "order-1001"
}

• id is Pulse’s id for the message. Keep it to check the message and to match its webhooks.
• category is the one Meta approved the template as (marketing, utility or authentication), never one the request chooses.
• charged is always ₹0.00 and balance_after is null: Pulse adds nothing per message. Meta bills your own card at its rate.

{
  "to": "+919876543210",
  "template": "hello_world",
  "language": "en_US"
}

Link buttons

Some templates have a button whose link is Pulse’s own: pulse.cloudfigma.com/l/… counts taps, and pulse.cloudfigma.com/p/… opens a payment link. For these, put the whole link in variables, at the button’s place, after the message’s own blanks. Pulse puts a short code of its own on the button. A link that cannot go is refused with 400 invalid_link, and nothing is sent.

{
  "to": "+919876543210",
  "template": "diwali_offer",
  "variables": [
    "Priya",
    "https://yourshop.com/diwali"
  ]
}

In the 24 hours after a customer last wrote to you, you can answer with your own words instead of a template. WhatsApp charges nothing for these replies. Send text in place of template:

curl -X POST https://pulse.cloudfigma.com/api/v1/messages \
  -H "Authorization: Bearer cfn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-5521-reply-1" \
  -d '{
    "to": "+919876543210",
    "text": "Yes, your order left this morning. It arrives tomorrow.",
    "client_ref": "ticket-5521"
  }'

{
  "id": "cm2msg0003",
  "status": "sent",
  "to": "+919876543210",
  "category": "service",
  "charged": "₹0.00",
  "balance_after": null,
  "client_ref": "ticket-5521"
}

• It goes to WhatsApp straight away, so status is already sent. Your team sees it in the Pulse Inbox, in the chat, as the business’s reply. category is service and charged is ₹0.00.
• text is 1 to 4,096 characters, and not only spaces. Otherwise: 400 invalid_text.
• Send text or template, never both. variables, language and header belong to templates; beside text they are refused with 400 invalid_request.
• Outside the window, or to someone who has never written to you: 409 window_closed. Nothing is sent. Send an approved template instead.
• If WhatsApp refuses the message: 502 send_failed, with the message’s id. It is kept as failed, as it would be in the Inbox.

A timeout does not tell you whether the message went. Send an Idempotency-Key header, unique to each message (your order id, or a UUID), and a retry is safe:

• Same key, same body: 200 with the first message’s id and "idempotent_replay": true. Nothing is sent again.
• Same key, different body: 422 idempotency_conflict. Use a new key for each different message.
• A plain-text reply still being sent with that key: 409 idempotency_in_progress. Ask again in a moment.
• A request that was refused does not use up its key, so the same request can go once the reason is gone.

Every request example on this page sends one, and payment requests take the same header.

A 202 means accepted, not delivered. To see where a message has got to, ask with its id and your key:

GET https://pulse.cloudfigma.com/api/v1/messages/{id}

{
  "id": "cm2msg0002",
  "status": "read",
  "to": "+919876543210",
  "category": "utility",
  "client_ref": "order-1001",
  "error_code": null,
  "error_detail": null,
  "refunded": false,
  "created_at": "2026-10-09T10:00:00.000Z",
  "delivered_at": "2026-10-09T10:00:05.000Z",
  "read_at": "2026-10-09T10:02:41.000Z",
  "links": []
}

• status moves queued → sent → delivered → read, or ends at failed.
• error_code and error_detail say why a message failed: WhatsApp’s error code, and what it means in words. Meta does not bill a message it could not deliver.
• refunded says whether a charge for a failed message was given back. Pulse charges nothing per message, so it stays false.
• created_at, delivered_at and read_at are ISO 8601 times in UTC; the last two stay null until it happens.
• links lists a tap-counting button’s page, its clicks, and the first and last tap. Empty for a message without one.
• An id that is not one of your account’s messages: 404 not_found.

Webhooks tell you the same as it happens, without asking.

Instead of asking, your server can be told. The account owner adds your https URL in Pulse under Settings › Developers, chooses its events, and copies its signing secret (whsec_…), which is shown once. Pulse then posts each event to the URL as JSON as it happens.

What arrives

Every request has the same envelope: id (this delivery, the same on every retry), event, version (1), created_at (when it happened) and data. Numbers are written +919876543210, times are ISO 8601 in UTC, and a field the send API returns has the same name here: id is Pulse’s message id, client_ref is yours.

POST /pulse-webhook HTTP/1.1
Content-Type: application/json
User-Agent: CloudFigma-Pulse-Webhooks/1
X-Pulse-Event: message.received
X-Pulse-Delivery: cm2dlv0001
X-Pulse-Timestamp: 1760004000
X-Pulse-Signature: sha256=3b1f6c…(64 hex characters)

{
  "id": "cm2dlv0001",
  "event": "message.received",
  "version": 1,
  "created_at": "2026-10-09T10:00:00.000Z",
  "data": {
    "message": {
      "id": "cm2msg0001",
      "wa_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgg",
      "from": "+919876543210",
      "type": "text",
      "text": "Is my order out for delivery?",
      "media": null,
      "reply_to_wa_message_id": null,
      "received_at": "2026-10-09T10:00:00.000Z"
    },
    "conversation_id": "cm2conv0001"
  }
}

Examples. Version 1 may gain fields; none is renamed or removed without a version 2.

Check the signature

X-Pulse-Signature is sha256= and the hex HMAC-SHA256 of X-Pulse-Timestamp, a dot and the raw request body, keyed with your webhook’s whole signing secret, whsec_ included. Compute it over the bytes you received, before parsing the JSON; compare in constant time; and refuse a timestamp more than 5 minutes from your clock, so a captured request cannot be replayed.

const crypto = require("crypto")
const express = require("express")
const app = express()

// Your webhook's secret (whsec_…), shown once.
const SECRET = process.env.PULSE_WEBHOOK_SECRET

// express.raw keeps the exact bytes it was sent.
app.post(
  "/pulse-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ts = req.get("X-Pulse-Timestamp") || ""
    const sig = req.get("X-Pulse-Signature") || ""
    const expected = "sha256=" + crypto
      .createHmac("sha256", SECRET)
      .update(ts + "." + req.body)
      .digest("hex")

    const fresh =
      Math.abs(Date.now() / 1000 - Number(ts)) <= 300
    const valid = sig.length === expected.length &&
      crypto.timingSafeEqual(
        Buffer.from(sig), Buffer.from(expected))
    if (!fresh || !valid) return res.sendStatus(401)

    const event = JSON.parse(req.body)
    // event.id repeats on a retry: skip it if seen.
    console.log(event.event, event.data)

    res.sendStatus(200) // within 10 s; slow work after
  },
)

app.listen(3000)

Answering and retries

• Answer with any 2xx within 10 seconds, then do slow work. Anything else is a failure, including no answer and a redirect: Pulse never follows one.
• A failed event is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours: 6 attempts in all. Then it is marked failed in the URL’s delivery log in Pulse, where Retry now sends it again.
• Delivery is at least once and not in order: skip an id you have handled, and order by the event’s own time.
• After 20 failures in a row, Pulse switches the URL off and emails the account owner. Events while it is off are not kept.
• URLs must be https and on the public internet. Pulse checks the address it connects to on every attempt.
• Send test event, in Settings, posts a ping signed like any other, with { "test": true, "endpoint": { "id", "url" } } as its data.

With the business’s own Razorpay connected in Pulse (Settings › Payments), one request asks a customer for money on WhatsApp. Pulse makes a Razorpay payment link for exactly the amount, in the business’s own Razorpay account, and sends it: as a free reply inside the customer’s 24-hour window, or else as an approved template with Pulse’s Pay now button. The money goes straight to the business’s Razorpay.

POST https://pulse.cloudfigma.com/api/v1/payment-requests
Authorization: Bearer cfn_live_YOUR_KEY
Content-Type: application/json
Idempotency-Key: order-10482

{
  "to": "+919876543210",
  "amount": "800.00",
  "purpose": "Cleaning, 7 Oct",
  "due_date": "2026-10-16",
  "client_ref": "order-10482"
}

• amount is rupees with at most two decimals, ₹1.00 or more; or send amount_paise as a whole number. purpose is required. due_date is YYYY-MM-DD; left out, a week from today.
• template names an approved template with a Pay now button, for outside the window; left out, the first one the account has. language and client_ref work as they do for messages.
• It answers 201 with the request: its id, status (requested, opened, paid, expired or cancelled), amount, payment_link, sent_as (text or template) and message_id.
• GET /api/v1/payment-requests/{id} says where it has got to. Once paid, payment holds Razorpay’s payment id, the amount and the method. Only Razorpay can mark a request paid.
• Asked again with the same Idempotency-Key, it answers 200 with the same request and "idempotent_replay": true, and makes no second link.

Every error answers { "error": …, "message": … }. Check error in your code; show or log message, which says what to fix. Nothing is sent when a request is refused.

A 500 never carries the fault itself. It carries a request_id, also sent as the x-request-id header: if a retry a minute later fails too, send it to support@cloudfigma.com and we can find what happened.

{
  "error": "internal_error",
  "message": "Something went wrong on our side. Try again in a minute; if it keeps happening, send us this request_id.",
  "request_id": "5b0e7c2a-91d4-4f3e-8a61-2f6c0d9e4b17"
}

• 6,000 requests a minute per API key, across every endpoint. Past it, 429 rate_limited: wait retry_after_seconds, then try again.
• Request bodies up to 5 MB. A file for a template goes as a link in header, not in the body.
• A plain-text reply up to 4,096 characters.
• Template messages wait in a queue for your number and go to WhatsApp in turn, so a burst is sent rather than refused.
• Webhooks: answer within 10 seconds.

{
  "error": "rate_limited",
  "message": "Too many requests, the limit is 6000 per minute. Retry in 42s.",
  "retry_after_seconds": 42
}

Questions about the API: support@cloudfigma.com.