WhatsApp overview
The WhatsApp API lets you send and receive WhatsApp Business messages — text, media, interactive menus, templates and broadcasts — over plain REST, using the same connected number your team uses in the dashboard. This page is the map: it shows the two API surfaces, the response envelope, and links to the reference page for every message type.
Connect a number first
Every WhatsApp call targets a channel — a WhatsApp Business number you've already connected to your org. If you haven't done that yet, follow the WhatsApp guide to connect a number through the "WhatsApp Business, set up for you" path. Once a number is live you can drive it entirely over HTTP.
With an app key, the routes work on Meta Cloud numbers — native or connected through your own Meta app — plus plain text on WhatsApp Web numbers when the app holds the whatsapp:web scope. With your org API key they work on every number in your WhatsApp inbox: Meta Cloud, partner numbers (GupShup, Plivo, AiSensy) and WhatsApp Web. Media, interactive messages, locations, contacts and reactions need a Meta Cloud number either way — the full matrix is in Which numbers support what.
The two surfaces
The same operations are exposed through two authenticated surfaces. Sending from your own org? Use your org API key — the quickstart walks it end to end. Each reference page shows the app-key route first (what apps that other orgs install use) and the org-key route in a With your org API key section; the full org-key route list is in the API reference.
| Surface | Base URL | Auth | Use it for |
|---|---|---|---|
| Org API | https://api.telenow.ai/api/orgs/{orgId} | Org API key: X-API-Key: vai_live_… — or a user JWT: Authorization: Bearer <jwt> + X-Org-Id: {orgId} | Your own server or dashboard, sending from your own org — no app needed |
| App API | https://api.telenow.ai/api/app-whatsapp | App key: Authorization: Bearer vai_app_… (or X-App-Key: vai_app_…) + scopes | Apps that other orgs install — each key carries only the scopes that org approved |
See Authentication & channels to get a key, pick scopes, and look up your channelId.
The response envelope
Every WhatsApp response, on both surfaces, is wrapped:
{ "success": true, "data": { "wamid": "wamid.HBgLMTQx…" } }
On failure:
{ "success": false, "error": "This contact hasn't messaged you in 24 hours — send an approved template to reopen the conversation." }
The returned wamid is WhatsApp's message id — match it against delivery status events later. To make retries safe, send an Idempotency-Key header: a retry with the same key within 24 hours returns the original response instead of sending twice. Every request without a dashboard login counts against 2,000 requests per 15 minutes per IP address, and app keys also have roughly 20 req/s (burst 60) per app; over either you get a 429 with retryAfter. Request bodies are capped at 2 MB (media upload routes allow up to 101 MB). Details: Errors & limits.
Message types & pages
Every POST /send carries exactly one content field. Pick the page for what you want to send:
| What you're sending | Content field | Page |
|---|---|---|
| Free-form text | message (body with the org key) | Text messages |
| Quoting a specific message (threaded reply) | reply_to (any type) | Reply to a message |
| Image, audio, video, document, sticker | mediaId (+ caption) | Media messages |
| Reply buttons, list menus, CTA-URL | interactive | Interactive messages |
| A pin on a map, or a shared contact card | location · contacts | Location & contacts |
| A pre-approved template message | (via /send-template) | Send a template |
| Create / edit templates | (via /channels/{id}/templates) | Manage templates |
| Read receipts & typing indicators | (via /messages/read) | Typing & receipts |
| A template blast to many contacts | (via /campaigns) | Broadcasts |
| Auto-replying with an AI agent, or answering calls | (agent binding) | AI agent & calling |
| Reading threads & message history | (via /threads) | Conversations |
| Assigning & resolving conversations, contacts, saved audiences, quick replies, business profile | (org key) | Inbox, contacts & segments |
| Receiving inbound messages & delivery status | (webhooks) | Webhooks |
| Number quality, verification & payment status | (via /health, org key) | Account health |
| Handling send failures | (400 hints, 502 provider errors) | Errors |
The 24-hour window
WhatsApp only lets you send free-form messages (text, media, interactive, location, contacts, reactions) inside the 24-hour customer service window — the 24 hours following the contact's most recent inbound message. Each new inbound message reopens the window.
Outside that window — or to start a brand-new conversation — you must send a pre-approved template. If you try free-form outside the window you get a 400 saying the contact hasn't messaged you in 24 hours (Meta code 131047), or the send is accepted and then fails as a whatsapp.message.status event. See Send a template and Errors.
Deferred features
These are honestly not built yet — don't design against them:
- Carousel and limited-time-offer templates.
- Flows, catalog / product-list (MPM) buttons, and WhatsApp Pay.
- One-tap OTP authentication buttons (only
COPY_CODEOTP is supported). - Inbound voice-note transcription.
- Webhook events for partner and WhatsApp Web numbers —
received/statusevents fire for Meta Cloud numbers only.
Related
- Authentication & channels — get a key, scopes, find your
channelId. - API reference — every route on both surfaces · Inbox, contacts & segments.
- Text · Media · Interactive · Location & contacts.
- Send a template · Manage templates · Broadcasts.
- Typing & receipts · AI agent & calling · Conversations · Webhooks · Errors.