Documentation

Everything you need to launch & build.

Set up your workspace, connect your WhatsApp number, run your team day to day — and integrate anything with our REST API, signed webhooks and Node.js SDK.

~10 minFrom sign-up to live
40REST endpoints
11Webhook events
HMACSigned deliveries
Get started

Overview

Watarang is built on the official WhatsApp Business Platform (Cloud API). You get a shared team inbox, no-code automations and chatbots, broadcasts, WhatsApp Flows and payments — plus a versioned REST API and signed webhooks for anything custom. Pick the path that fits you:

Get started

Quick start — live in five steps

Most businesses go from sign-up to their first WhatsApp message in about ten minutes.

  1. Create your workspace

    Sign up with your work email, enter the 6-digit verification code and choose a plan. The 7-day free trial needs no credit card.

  2. Connect your WhatsApp number

    During onboarding, connect with Facebook (recommended) or enter your own Cloud API credentials. Messaging features unlock as soon as the number is connected.

  3. Add your contacts

    Add customers one by one or import them, then tag them (for example vip, leads) so you can target broadcasts and automations.

  4. Create a message template

    Write a Marketing, Utility or Authentication template and submit it to Meta. Approval is usually quick — you’ll see the status update in Templates.

  5. Send, automate and grow

    Launch a broadcast, turn on a welcome automation or chatbot, and reply to customers from the shared inbox.

Tip: invite your team before your first broadcast so replies are assigned to the right people from day one (Settings → Team).
Get started

Connect your WhatsApp number

Choose how to connect during onboarding. You can review the connection status any time in Settings.

RecommendedConnect with Facebook

Meta’s Embedded Signup opens in a pop-up. Log in, choose or create your Meta Business account and WhatsApp Business Account, then verify your phone number with a code. No tokens to copy.

AdvancedUse your own Cloud API credentials

Already set up in Meta for Developers? Provide your phone number ID, WhatsApp Business Account ID and a permanent system-user access token, then point Meta’s webhook at Watarang.

Before you start: the number must be able to receive an SMS or voice call for verification, and it can only be connected to one WhatsApp API provider at a time.
Get started

Team members & roles

Every workspace has one owner. Invite managers and staff so each person sees exactly what they need.

AreaOwnerManagerStaff
Overview, Inbox, Contacts✓✓✓
Bookings & Services✓✓✓
Broadcasts, Templates, Flows✓✓—
Automations, Chatbot, Lead forms, QR codes✓✓—
Analytics, Catalog, Integrations, Logs✓✓—
Billing, API keys, Webhooks✓——
Workspace

Feature guide

A quick tour of everything in your sidebar.

Team inbox

Every WhatsApp conversation in one shared inbox — assign chats, add notes and resolve them as a team.

Contacts

Your WhatsApp CRM: tags, notes, opt-in status and full message history for every customer.

Templates

Create Marketing, Utility and Authentication templates and track Meta approval.

Broadcasts

Send approved templates to tagged audiences now or on a schedule, then track delivery and reads.

Automations

Welcome messages, drips, reminders and COD-to-prepaid nudges that run 24/7.

Chatbot

No-code keyword and menu bots that answer common questions instantly.

WhatsApp Flows

In-chat forms for bookings, lead capture and orders — no website needed.

Lead forms

Shareable forms that drop new leads straight into your contacts.

QR codes

Print or share QR codes that open a chat with a pre-filled message.

Bookings & services

List your services and manage appointments customers book over WhatsApp.

Catalog

Showcase products so customers can browse and ask about them in chat.

Analytics

Messaging volume and campaign performance at a glance.

Workspace

WhatsApp messaging rules

These rules come from WhatsApp itself and apply to every provider. Knowing them avoids most “why didn’t this send?” questions.

  • 24-hour customer service window. After a customer messages you, you can reply freely for 24 hours. Outside that window, start the conversation with an approved template.
  • Templates need approval. Marketing, Utility and Authentication templates are reviewed by Meta before you can send them.
  • Opt-in matters. Only message people who agreed to hear from you — it protects your number’s quality rating and sending limits.
  • Media first, then send. Images, video, audio, documents and stickers are uploaded once and referenced by ID.
Protect your quality rating. High block or report rates can lower your number’s quality and messaging limits. Keep broadcasts relevant and easy to opt out of.
Workspace

Status reference

The statuses you’ll see across the workspace and the API.

ObjectStatuses
MessageSENT → DELIVERED → READ, or FAILED
ConversationOPEN · PENDING · RESOLVED · CLOSED
TemplatePENDING → APPROVED or REJECTED · DISABLED
BroadcastDRAFT → SCHEDULED → SENDING → SENT, or FAILED
FlowDRAFT → PUBLISHED → DEPRECATED
MediaPENDING → READY, or FAILED
Webhook deliveryPENDING → DELIVERED, or FAILED → DEAD_LETTER
Developers

Authentication

The public API lives at https://www.watarang.com/api/v1 and speaks JSON. Every request needs an API key sent as a Bearer token. Owners create keys in Settings → API Keys or the developer portal.

Request header
Authorization: Bearer YOUR_API_KEY
  • One key, one business. A key only ever sees its own workspace — GET /business always means “my business”.
  • Scoped by resource. Grant only the resource:read / resource:write scopes an integration needs.
  • Server-side only. Never put a key in a browser, mobile app or public repository. Revoke and rotate keys from the dashboard.
ResourceReadWriteWhat it unlocks
contactscontacts:readcontacts:writeCreate, update, tag, block and delete contacts
conversationsconversations:readconversations:writeList and open conversations, filter by status
messagesmessages:readmessages:writeRead message history and send messages
templatestemplates:readtemplates:writeManage local template drafts (Meta submission stays in the dashboard)
broadcastsbroadcasts:readbroadcasts:writeCreate, schedule and track broadcasts
flowsflows:readflows:writeManage WhatsApp Flows and send published flows
mediamedia:readmedia:writeUpload, list and download images, video, audio and documents
webhookswebhooks:readwebhooks:writeRegister endpoints and inspect delivery history
teamteam:read—List team members and roles
businessbusiness:read—Your own business profile and connected numbers
analyticsanalytics:read—Messaging and campaign analytics
Developers

Your first request

List your contacts, then send a message. Replace $WATARANG_API_KEY with your key.

curl "https://www.watarang.com/api/v1/contacts?limit=10" \
  -H "Authorization: Bearer $WATARANG_API_KEY"
Response · 200 OK
{
  "data": [
    {
      "id": "cm8x2k1qz0001ab12cd34ef56",
      "name": "Asha Verma",
      "phone": "919876543210",
      "email": null,
      "tags": ["vip"],
      "isBlocked": false
    }
  ],
  "pagination": { "nextCursor": "eyJpZCI6ImNtOHgyazFxeiJ9", "hasMore": true }
}

Send a message

POST /messages needs a contactId. Set type to TEXT with content, or send media by passing a mediaId from POST /media.

curl -X POST "https://www.watarang.com/api/v1/messages" \
  -H "Authorization: Bearer $WATARANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "contactId": "cm8x2k1qz0001ab12cd34ef56",
    "type": "TEXT",
    "content": "Hi Asha, your order has shipped!"
  }'
Free-form text only delivers inside the 24-hour customer service window. To reach a contact outside it, send an approved template (for example via a broadcast).
Developers

Endpoints

All paths are relative to https://www.watarang.com/api/v1. List endpoints accept limit and cursor.

Contactscontacts
GET/contactsList contacts (filter by tag)
POST/contactsCreate a contact
GET/contacts/{id}Retrieve a contact
PATCH/contacts/{id}Update a contact or block / unblock
DELETE/contacts/{id}Delete a contact
Conversations & messagesconversations · messages
GET/conversationsList conversations (OPEN, PENDING, RESOLVED, CLOSED)
POST/conversationsOpen a conversation
GET/conversations/{id}Retrieve a conversation
GET/messagesList messages
POST/messagesSend a message to a contact
Templatestemplates
GET/templatesList templates
POST/templatesCreate a local draft
GET/templates/{id}Retrieve a template
PATCH/templates/{id}Update a draft
DELETE/templates/{id}Delete a template
Broadcastsbroadcasts
GET/broadcastsList broadcasts
POST/broadcastsCreate — sends immediately unless scheduled
GET/broadcasts/{id}Retrieve a broadcast and its stats
PATCH/broadcasts/{id}Update a draft or scheduled broadcast
DELETE/broadcasts/{id}Delete a broadcast
Flowsflows
GET/flowsList flows (DRAFT, PUBLISHED, DEPRECATED)
POST/flowsCreate a flow
GET/flows/{id}Retrieve a flow
PATCH/flows/{id}Update a flow
DELETE/flows/{id}Delete a flow
POST/flows/{id}/sendSend a published flow to one contact
Mediamedia
GET/mediaList media (IMAGE, VIDEO, AUDIO, DOCUMENT, STICKER)
POST/mediaUpload media
GET/media/{id}Retrieve media metadata
DELETE/media/{id}Delete media
GET/media/{id}/fileStream the raw file (or ?variant=thumbnail)
Webhookswebhooks
GET/webhooksList webhook endpoints
POST/webhooksRegister an endpoint — secret is shown once
PATCH/webhooks/{id}Update URL, events or status
DELETE/webhooks/{id}Remove an endpoint
GET/webhooks/{id}/deliveriesDelivery history for one endpoint
Account (read-only)team · business · analytics
GET/teamList team members
GET/businessYour own business
GET/whatsapp-accountsConnected WhatsApp numbers
GET/analyticsMessaging and campaign analytics
Developers

Pagination

Every list endpoint uses cursor pagination. Ask for up to 100 items with limit (default 30), then pass pagination.nextCursor back as cursor while hasMore is true. There’s no total count — that keeps large lists fast.

Node.js
// One page at a time
let cursor: string | undefined
do {
  const page = await watarang.contacts.list({ limit: 100, cursor })
  for (const contact of page.data) console.log(contact.name)
  cursor = page.pagination.hasMore ? page.pagination.nextCursor : undefined
} while (cursor)

// …or let the SDK walk every page lazily
for await (const contact of watarang.contacts.listAll({ tag: "vip" })) {
  console.log(contact.name)
}
Developers

Errors

Errors always share one shape. Branch on the stable code; show message to humans; quote requestId when you contact support.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is missing the messages:write scope.",
    "requestId": "req_7Hd2kQ"
  }
}
StatusMeaningWhat to do
401Missing, invalid, revoked or expired API keyCheck the header and key status
403Key lacks the required scope, or its IP allowlist rejected youAdd the scope or allow the IP
404No such resource in your businessCheck the ID
409A resource with the same unique fields existsFetch and update instead
429Rate limit reachedWait for Retry-After seconds
5xxTemporary server problemRetry with backoff
Developers

Rate limits

Limits use a one-minute sliding window and apply at three levels — whichever you hit first wins.

120 / min

Per API key

300 / min

Per business, across all keys

300 / min

Per client IP address

Every response tells you where you stand; a 429 also says how long to wait.

Headers
HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1763049660

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Developers

Idempotency

Network retries shouldn’t send a message twice. Add an Idempotency-Key header to POST /messages and POST /broadcasts: a repeat request with the same key within 24 hours returns the original response instead of running again.

Use a key that describes the action, such as order-1042-shipped. The Node.js SDK adds a random key automatically when you don’t pass one.
Webhooks

Webhook events

Webhooks push events to your server the moment they happen. Register an HTTPS endpoint with the events you want — the response includes a signing secret that is shown only once, so store it safely.

cURL
curl -X POST "https://www.watarang.com/api/v1/webhooks" \
  -H "Authorization: Bearer $WATARANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/watarang",
    "events": ["message.received", "message.read", "form.submitted"]
  }'
EventSent when
message.receivedA contact sent you a message.
message.deliveredAn outbound message reached the contact’s phone.
message.readThe contact read your message (when read receipts are on).
message.failedWhatsApp could not deliver an outbound message.
contact.createdA new contact was added — manually, by import, form or API.
form.submittedSomeone submitted one of your lead forms.
broadcast.completedA broadcast finished sending to its audience.
flow.completedA contact completed a WhatsApp Flow.
flow.expiredA sent flow expired before the contact completed it.
template.approvedMeta approved one of your message templates.
template.rejectedMeta rejected one of your message templates.
Webhooks

Verifying signatures

Every delivery carries X-Watarang-Signature (sha256= + hex) and X-Watarang-Timestamp (Unix seconds). The signature is an HMAC-SHA256 of {timestamp}.{raw body} using your endpoint secret. Reject anything that doesn’t match or is more than 5 minutes old.

Example delivery
POST /webhooks/watarang HTTP/1.1
Content-Type: application/json
X-Watarang-Signature: sha256=6f1ed002ab5595859014ebf0951522d9…
X-Watarang-Timestamp: 1763049600

{
  "event": "message.received",
  "data": { … }
}
import express from "express"
import { verifyWebhookSignature, WatarangSignatureVerificationError } from "@watarang/node"

app.post("/webhooks/watarang", express.raw({ type: "application/json" }), (req, res) => {
  try {
    verifyWebhookSignature({
      payload: req.body.toString("utf8"), // the raw body — do not JSON.parse first
      signature: req.header("X-Watarang-Signature")!,
      timestamp: req.header("X-Watarang-Timestamp")!,
      secret: process.env.WATARANG_WEBHOOK_SECRET!,
    })
  } catch (err) {
    if (err instanceof WatarangSignatureVerificationError) return res.status(400).end()
    throw err
  }

  const event = JSON.parse(req.body.toString("utf8"))
  // handle event.event / event.data, then acknowledge quickly
  res.status(200).end()
})
Verify against the raw request body. Parsing and re-serialising the JSON first changes the bytes and the signature will never match.
Webhooks

Deliveries & retries

Respond with any 2xx within 8 seconds to acknowledge a delivery. Anything else — or a timeout — is retried on this schedule:

AttemptWhen
1Immediately
21 minute later
35 minutes later
430 minutes later
52 hours later
66 hours later — then DEAD_LETTER
  • Acknowledge fast, work later. Queue the event and return 200 straight away.
  • Expect duplicates. Make handlers idempotent — retries can deliver the same event more than once.
  • Inspect history. GET /webhooks/{id}/deliveries lists attempts with their status.
SDK

Node.js / TypeScript SDK

The official SDK handles authentication, retries with backoff, pagination, idempotency keys and webhook verification. It is typed end to end.

Install
npm install github:vasvionlabs/watarang#path:sdk/node
Quick start
import { WatarangClient } from "@watarang/node"

const watarang = new WatarangClient({
  apiKey: process.env.WATARANG_API_KEY!,
  // baseUrl: "http://localhost:3000/api/v1", // local or self-hosted
})

const contact = await watarang.contacts.create({ name: "Asha Verma", phone: "919876543210" })
await watarang.messages.send({ contactId: contact.id, type: "TEXT", content: "Welcome aboard, Asha!" })
  • Resources: contacts, conversations, messages, templates, broadcasts, flows, media, webhooks, team, business and analytics.
  • Retries: network errors, 429 and 5xx are retried automatically (honouring Retry-After); 4xx errors are not.
  • Other languages: PHP, Python, Java, Go and .NET SDKs are planned — the REST API works from any language today.
Help

Frequently asked questions

Do I need a Meta Business account?

Yes. The WhatsApp Business Platform runs through Meta. If you connect with Facebook during onboarding, the Embedded Signup flow walks you through creating or choosing your Meta Business account and WhatsApp Business Account in a few clicks.

Why can’t I send a normal message to some contacts?

WhatsApp only allows free-form messages within 24 hours of the customer’s last message to you. Outside that window you must start the conversation with an approved template — that’s why broadcasts always use templates.

How long does template approval take?

Meta reviews most templates within minutes, but it can take up to 24 hours. You’ll see the status change in Templates, and you can subscribe to the template.approved and template.rejected webhooks.

Where do I get an API key?

Owners can create keys in Settings → API Keys or in the developer portal at /developers. Pick only the scopes your integration needs, store the key on your server, and never ship it in a browser or mobile app.

Why are some sidebar items locked?

Messaging features unlock once a WhatsApp number is connected. Overview, Settings and Logs are always available, so you can finish setup first.

Is my data secure?

Data is encrypted (AES-256), API keys are scoped per resource and can be IP-restricted, and every webhook delivery is signed with HMAC-SHA256 and a timestamp so you can reject forged or replayed requests.

Help

Talk to a human

Stuck, or want a hand going live? We support customers in English, Hindi and Telugu.

Ready to go live?

Start your 7-day free trial — no credit card, live in about 10 minutes.