Overview
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.
These APIs work on native channels only — numbers provisioned through Meta Cloud on the platform. Numbers attached through other integrations aren't addressable here.
The two surfaces
The same operations are exposed through two authenticated surfaces. This section of the docs teaches the app-key (programmatic) surface — it's what most integrations use.
| Surface | Base URL | Auth | Use it for |
|---|---|---|---|
| Programmatic API (primary) | https://api.telenow.ai/api/app-whatsapp | App key: Authorization: Bearer vai_app_… (or X-App-Key: vai_app_…) + scopes | Your own backends, automations, bots |
| Dashboard API | https://api.telenow.ai/api/orgs/{orgId} | User JWT: Authorization: Bearer <jwt> + X-Org-Id: {orgId} | Your own dashboard / back-office UI |
See Authentication & channels to get an app key, pick scopes, and look up your channelId.
The response envelope
Every app-key WhatsApp response is wrapped:
{ "success": true, "data": { "wamid": "wamid.HBgLMTQx…" } }
On failure:
{ "success": false, "error": "131047: 24-hour window closed — send an approved template" }
The returned wamid is WhatsApp's message id. There's no idempotency key — dedupe on the wamid you get back, and match it against delivery status events later. The API is rate-limited to roughly 20 req/s (burst 60); over that you get a 429 with { "error": "Data API rate limit reached — slow down", "retryAfter": 1 }. Request bodies are capped at 2 MB (media upload routes allow up to 101 MB).
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 | 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 |
| Receiving inbound messages & delivery status | (webhooks) | Webhooks |
| Number quality, verification & payment status | (via /health) | Account health |
| Handling send failures | (400 codes) | 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 with Meta code 131047. 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.
- Sending / reading over org keys (
/api/v1): org keys can receive webhook events, but send and read are app-key only.
Related
- Authentication & channels — get a key, scopes, find your
channelId. - Text · Media · Interactive · Location & contacts.
- Send a template · Manage templates · Broadcasts.
- Typing & receipts · AI agent & calling · Conversations · Webhooks · Errors.