API reference index
A one-page cheatsheet of the whole WhatsApp API surface — each row links to the page with the full request/response detail.
App-key API
Base https://api.telenow.ai/api/app-whatsapp · auth Authorization: Bearer vai_app_… (or X-App-Key: vai_app_…). Works on Meta Cloud numbers; plain text also on WhatsApp Web numbers with the whatsapp:web scope.
| Method | Path | Scope | Purpose | Docs |
|---|---|---|---|---|
| GET | /channels | whatsapp | List Meta Cloud numbers (and WhatsApp Web numbers with whatsapp:web) | wa-auth |
| POST | /send | whatsapp | Send one free-form message | wa-text |
| POST | /send-template | whatsapp | Send a pre-approved template | wa-send-template |
| POST | /messages/read | whatsapp | Read receipt + typing | wa-typing |
| POST | /channels/{id}/media | whatsapp | Upload/stage media (≤ 101 MB) | wa-media |
| GET | /media/{id} | whatsapp | Download media (by message UUID) | wa-media |
| GET | /channels/{id}/templates | whatsapp | List approved templates | wa-send-template |
| POST | /channels/{id}/templates | whatsapp:templates | Create a template | wa-templates |
| POST | /channels/{id}/templates/media | whatsapp:templates | Stage a media-header for a template def | wa-templates |
| PATCH | /templates/{tid} | whatsapp:templates | Edit/resubmit a template (note: NOT nested under /channels) | wa-templates |
| POST | /campaigns | whatsapp:campaign | Create + start a broadcast | wa-broadcasts |
| GET | /campaigns/{id} | whatsapp:campaign | Broadcast status (campaigns this app created) | wa-broadcasts |
| POST | /campaigns/{id}/pause | whatsapp:campaign | Pause a broadcast | wa-broadcasts |
| POST | /campaigns/{id}/cancel | whatsapp:campaign | Cancel a broadcast | wa-broadcasts |
| GET | /channels/{id}/threads | whatsapp | List conversations | wa-conversations |
| GET | /threads/{id}/messages | whatsapp | Message history for a thread | wa-conversations |
Org API key routes
Base https://api.telenow.ai/api/orgs/{orgId} · auth X-API-Key: vai_live_… (or a dashboard login). The key is pinned to its own org; any non-GET needs an owner, admin or developer key. The Creator column is the role the key's creator must hold in the org: M any member, OA owner/admin, OAD owner/admin/developer. Bodies and responses use snake_case unless noted. See Use your org API key instead.
/whatsapp-hub — numbers, sending, inbox
| Method | Path | Purpose | Creator | Docs |
|---|---|---|---|---|
| GET | /channels | Every number in your inbox | M | wa-quickstart |
| POST | /channels/{id}/send | Send { to, body | mediaId (+caption) | location | reaction | contacts | interactive, reply_to? } → { wamid } | M | wa-text |
| POST | /channels/{id}/send-template | Send { to, template, language?, variables?, components? } → { wamid } | M | wa-send-template |
| GET | /channels/{id}/templates | Templates this number can send (?for=broadcast|agent_tool) | M | wa-send-template |
| POST | /channels/{id}/media | Upload media (multipart file, Meta Cloud only) → { mediaId, … } | M | wa-media |
| GET | /media/{messageId} | Download a message's media | M | wa-media |
| GET | /channels/{id}/threads | Conversations (?status, assigned, q, tag, limit, offset) | M | wa-conversations |
| GET | /threads/{tid}/messages | Latest 200 messages — marks the thread read | M | wa-conversations |
| POST | /threads/{tid}/send, /threads/{tid}/send-template | Reply inside a conversation (same bodies, no to) | M | wa-text |
| PUT | /threads/{tid}/assign · /status · /pause | Assign { user_id }, set { status, snoozed_until? }, pause AI { paused } | M | wa-inbox |
| GET | /channels/{id}/inbox-health | Response-time stats (?days, threshold_mins) | M | wa-inbox |
| GET, PATCH | /contacts, /contacts/tags, /contacts/{cid}, /contacts/by-phone/{phone} | Contacts — list, labels, read, edit | M | wa-inbox |
| GET, POST, DELETE | /segments, /segments/{sid}, POST /segments/preview | Saved audiences (save/delete need OAD) | M / OAD | wa-inbox |
| GET, POST, PUT, DELETE | /canned-replies, /canned-replies/{rid} | Saved quick replies | M | wa-inbox |
| PUT | /channels/{id}/agent | Bind the AI agent { agent_id?, ai_enabled, agent_opener? } | OA | wa-agent |
| PUT | /channels/{id}/calling-agent | WhatsApp calling { agent_id?, calling_enabled } | OA | wa-agent |
| GET | /channels/{id}/calls | Call log (newest 100) | M | wa-agent |
| PUT / GET | /channels/{id}/csat | Customer ratings — set up / read | OA / M | wa-agent |
| POST, DELETE | /channels, /channels/{id} | Add / remove a number in the inbox | OA | wa-inbox |
| GET | /linkable-connections, /channels/removed, /channels/{id}/webhook | Connections not yet in the inbox; removed numbers; inbound webhook settings | M | wa-inbox |
| POST | /channels/{id}/restore, /channels/{id}/purge | Restore a removed number; permanently delete it and its history | OA | wa-inbox |
Dashboard helpers you won't usually need: GET /channels/{id}/provider-webhook and POST /channels/{id}/register-webhook (pointing a partner at Telenow), and GET/POST /views, DELETE /views/{vid} (saved inbox filters).
/whatsapp-campaigns — broadcasts
| Method | Path | Purpose | Creator | Docs |
|---|---|---|---|---|
| GET | /, /{id}, /{id}/recipients | List campaigns; one campaign with status counts; recipients (?status, limit, offset) | M | wa-broadcasts |
| POST | / | Create a draft | OAD | wa-broadcasts |
| POST | /{id}/recipients, /{id}/recipients-from-segment | Add recipients (≤ 20,000 per call) or a saved audience (≤ 5,000, with capped) | OAD | wa-broadcasts |
| POST | /{id}/start, /{id}/pause, /{id}/cancel | Start or resume, pause, cancel | OAD | wa-broadcasts |
| GET / POST | /opt-outs | List / add opt-outs | M / OAD | wa-broadcasts |
/whatsapp-cloud/channels/{channelId} — Meta Cloud numbers
| Method | Path | Purpose | Creator | Docs |
|---|---|---|---|---|
| GET | /templates | Every template, any status, re-read from Meta | M | wa-templates |
| POST | /templates, /templates/media | Create a template (allow_category_change snake_case); upload a header sample | OA | wa-templates |
| PATCH / DELETE | /templates/{tid} | Edit and resubmit; delete every language of that template | OA | wa-templates |
| GET | /health | Account-health snapshot | M | wa-errors |
| GET / POST | /profile | Read / update the business profile | M / OA | wa-inbox |
Dashboard login only
An org API key gets 401 on these: the rest of /whatsapp-cloud (config, onboard, accounts, registrations, number eligibility, WABA numbers, usage) — see the Onboarding API — and /whatsapp/sessions/* (linking WhatsApp Web by QR).
Webhooks (org key)
Base https://api.telenow.ai/api/v1 · X-API-Key · flat JSON (no success/data envelope).
| Method | Path | Purpose | Docs |
|---|---|---|---|
| GET | /me | Check a key; returns org_id | wa-quickstart |
| GET | /hooks | List subscriptions → { hooks, total } | wa-webhooks |
| POST | /hooks | Subscribe a target_url to events (201) | wa-webhooks |
| DELETE | /hooks/{id} | Unsubscribe → { id, deleted } | wa-webhooks |
| GET | /events/sample | Sample payload for an event type | wa-webhooks |
Scopes are declared in the app manifest — see App scopes. Every failure code and hard limit lives in Errors & limits.