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:
Quick start — live in five steps
Most businesses go from sign-up to their first WhatsApp message in about ten minutes.
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.
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.
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.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.
Send, automate and grow
Launch a broadcast, turn on a welcome automation or chatbot, and reply to customers from the shared inbox.
Connect your WhatsApp number
Choose how to connect during onboarding. You can review the connection status any time in Settings.
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.
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.
Team members & roles
Every workspace has one owner. Invite managers and staff so each person sees exactly what they need.
| Area | Owner | Manager | Staff |
|---|---|---|---|
| Overview, Inbox, Contacts | ✓ | ✓ | ✓ |
| Bookings & Services | ✓ | ✓ | ✓ |
| Broadcasts, Templates, Flows | ✓ | ✓ | — |
| Automations, Chatbot, Lead forms, QR codes | ✓ | ✓ | — |
| Analytics, Catalog, Integrations, Logs | ✓ | ✓ | — |
| Billing, API keys, Webhooks | ✓ | — | — |
Feature guide
A quick tour of everything in your sidebar.
Every WhatsApp conversation in one shared inbox — assign chats, add notes and resolve them as a team.
Your WhatsApp CRM: tags, notes, opt-in status and full message history for every customer.
Create Marketing, Utility and Authentication templates and track Meta approval.
Send approved templates to tagged audiences now or on a schedule, then track delivery and reads.
Welcome messages, drips, reminders and COD-to-prepaid nudges that run 24/7.
No-code keyword and menu bots that answer common questions instantly.
In-chat forms for bookings, lead capture and orders — no website needed.
Shareable forms that drop new leads straight into your contacts.
Print or share QR codes that open a chat with a pre-filled message.
List your services and manage appointments customers book over WhatsApp.
Showcase products so customers can browse and ask about them in chat.
Messaging volume and campaign performance at a glance.
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.
Status reference
The statuses you’ll see across the workspace and the API.
| Object | Statuses |
|---|---|
| Message | SENT → DELIVERED → READ, or FAILED |
| Conversation | OPEN · PENDING · RESOLVED · CLOSED |
| Template | PENDING → APPROVED or REJECTED · DISABLED |
| Broadcast | DRAFT → SCHEDULED → SENDING → SENT, or FAILED |
| Flow | DRAFT → PUBLISHED → DEPRECATED |
| Media | PENDING → READY, or FAILED |
| Webhook delivery | PENDING → DELIVERED, or FAILED → DEAD_LETTER |
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.
Authorization: Bearer YOUR_API_KEY- One key, one business. A key only ever sees its own workspace —
GET /businessalways means “my business”. - Scoped by resource. Grant only the
resource:read/resource:writescopes 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.
| Resource | Read | Write | What it unlocks |
|---|---|---|---|
contacts | contacts:read | contacts:write | Create, update, tag, block and delete contacts |
conversations | conversations:read | conversations:write | List and open conversations, filter by status |
messages | messages:read | messages:write | Read message history and send messages |
templates | templates:read | templates:write | Manage local template drafts (Meta submission stays in the dashboard) |
broadcasts | broadcasts:read | broadcasts:write | Create, schedule and track broadcasts |
flows | flows:read | flows:write | Manage WhatsApp Flows and send published flows |
media | media:read | media:write | Upload, list and download images, video, audio and documents |
webhooks | webhooks:read | webhooks:write | Register endpoints and inspect delivery history |
team | team:read | — | List team members and roles |
business | business:read | — | Your own business profile and connected numbers |
analytics | analytics:read | — | Messaging and campaign analytics |
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"{
"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!"
}'Endpoints
All paths are relative to https://www.watarang.com/api/v1. List endpoints accept limit and cursor.
contactsconversations · messagestemplatesbroadcastsflowsmediawebhooksteam · business · analyticsPagination
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.
// 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)
}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"
}
}| Status | Meaning | What to do |
|---|---|---|
| 401 | Missing, invalid, revoked or expired API key | Check the header and key status |
| 403 | Key lacks the required scope, or its IP allowlist rejected you | Add the scope or allow the IP |
| 404 | No such resource in your business | Check the ID |
| 409 | A resource with the same unique fields exists | Fetch and update instead |
| 429 | Rate limit reached | Wait for Retry-After seconds |
| 5xx | Temporary server problem | Retry with backoff |
Rate limits
Limits use a one-minute sliding window and apply at three levels — whichever you hit first wins.
Per API key
Per business, across all keys
Per client IP address
Every response tells you where you stand; a 429 also says how long to wait.
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: 12Idempotency
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.
order-1042-shipped. The Node.js SDK adds a random key automatically when you don’t pass one.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 -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"]
}'| Event | Sent when |
|---|---|
message.received | A contact sent you a message. |
message.delivered | An outbound message reached the contact’s phone. |
message.read | The contact read your message (when read receipts are on). |
message.failed | WhatsApp could not deliver an outbound message. |
contact.created | A new contact was added — manually, by import, form or API. |
form.submitted | Someone submitted one of your lead forms. |
broadcast.completed | A broadcast finished sending to its audience. |
flow.completed | A contact completed a WhatsApp Flow. |
flow.expired | A sent flow expired before the contact completed it. |
template.approved | Meta approved one of your message templates. |
template.rejected | Meta rejected one of your message templates. |
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.
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()
})Deliveries & retries
Respond with any 2xx within 8 seconds to acknowledge a delivery. Anything else — or a timeout — is retried on this schedule:
| Attempt | When |
|---|---|
| 1 | Immediately |
| 2 | 1 minute later |
| 3 | 5 minutes later |
| 4 | 30 minutes later |
| 5 | 2 hours later |
| 6 | 6 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}/deliverieslists attempts with their status.
Node.js / TypeScript SDK
The official SDK handles authentication, retries with backoff, pagination, idempotency keys and webhook verification. It is typed end to end.
npm install github:vasvionlabs/watarang#path:sdk/nodeimport { 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.
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.
Talk to a human
Stuck, or want a hand going live? We support customers in English, Hindi and Telugu.
The fastest way to reach our team.
Start chat Email supportvasvionlabs@gmail.com
Send email Developer portalAPI keys, live API reference and SDK (sign-in required).
Open portalStart your 7-day free trial — no credit card, live in about 10 minutes.