The WhatsApp workspace behind every agent here: a shared inbox, campaigns gated on consent and template approval, a natural-language automation builder, and a 24-hour window guard that refuses a message Meta would otherwise accept and silently drop.
Wavy is the WhatsApp Business Platform workspace this product is built around — a shared team inbox, contacts and segments, broadcast campaigns, message templates, and an automation builder you describe in a sentence, all running against your own connected WhatsApp number.
It is the one agent here with a real send path, so it also carries the heaviest guardrails: a service-window check before every free-form reply, a consent sweep before every campaign launch, and a template validator that pre-checks the rules Meta enforces before a rejection can cost the account a utility restriction.
Every capability specified for Wavy is implemented to at least a partial state — there is nothing left in framework/capabilities.py unmarked for this agent. What you see as 'requires_configuration' above is the honest remainder: a credential only you can supply, not unbuilt work.
It will not send a free-form reply once the 24-hour window has closed
Meta accepts a free-form send outside the service window and then drops it, so Wavy checks first: the request is refused with a 409 naming the template alternative, before a sender is resolved and before any row claims to be sent. Scoped to the cloud rail only — a QR-paired handset has no Meta window and can message anyone at any hour.
It will not launch a marketing campaign around a missing opt-in
Every queued recipient is checked against a category-matched consent record before launch. A contact with no record is treated as not consented, never as assumed yes. Recipients that fail are marked suppressed_no_consent rather than silently dropped, so a launch reports '900 contacts, 400 reachable' instead of a shorter send nobody can explain — and a resume re-runs the same sweep, because consent can be withdrawn while a campaign sits paused.
It will not let an internal note reach a customer
A staff note is a ConversationNote, a different row type from Message with no direction, no provider id and no status. There is no code path from one to the other and no boolean flag that could be flipped — the two tables simply have no shape in common for a note to travel through.
It will not submit a template Meta would reject
Every rule Meta enforces on template content — category limits, button caps, authentication-template restrictions on URLs, media and emoji, media-header type mismatches — is checked before a submission leaves this server, because a rejected or miscategorised template can cost the account a 7-to-30-day utility restriction that is not something an owner can appeal quickly.
It will not invent a connector, an action, or a number a provider never sent
Describe an automation and a step naming a connector or action that does not exist is dropped and reported with the reason, never guessed at with something close. The same honesty applies to numbers: a WhatsApp number's quality rating and messaging tier are only ever Meta's own words, echoed back with from_provider stated — never computed locally and asserted as live.
Getting started
Add the number's display name and phone number. If you set it as the default for the workspace, every other number's default flag is cleared automatically so an outbound send is never ambiguous about which number it goes from.
This is what the SLA clock and any away-message actually use — an unassigned conversation that arrives at 11pm does not sit 'breaching' by the time a manager checks the queue at 9am, because unassigned conversations report a business-time wait alongside the wall-clock one.
Any role can claim an unheld conversation for themselves; claiming one someone else already holds is refused unless you are an owner or admin. That is what keeps a queue from turning into two agents replying to the same customer.
Capabilities
Assignment, claiming, internal notes, saved replies with contact-field placeholders, and an SLA clock that counts business time rather than wall time.
Will not: Cannot turn an internal note into a customer message — the two are different row types.
Owner, admin, agent and viewer, seeded per workspace, with a sixteen-entry permission catalogue — every entry of which governs at least one route, so revoking one on the Roles screen changes what the product does. Campaign, template, assignment, working-hours and integration changes are written to a queryable audit log.
Will not: Cannot edit a builtin role's permissions — that would let a workspace lock itself out.
A session cannot be created without a disclosure the customer sees. Handing off to a human is instant and idempotent, and it stops the bot from answering by marking the conversation operator-handled.
Will not: The handoff summary is templated from the last six messages, not written by a model.
A WhatsApp Calls channel inside the same inbox shell, its own call log and a Call Recordings page with a usage meter — all read against wavy_calls/wavy_call_recordings with no third-party credential. Webhook intake upserts per call, so a redelivered event updates one row instead of creating a second.
Needs: A Calling-enabled WhatsApp number (Meta grants this per number on request).
Will not: No recording is ever populated automatically: WhatsApp's Business Calling webhook carries call metadata, never audio, so an empty Call Recordings page means no ingestion path exists yet, not just 'no calls so far'.
A live consent record per (contact, category) plus an append-only event log, so a send-time check always reads current state and a regulator's question about how consent was obtained still has an answer.
Window arithmetic computed from real message timestamps, reported per conversation and as an at-risk list, and enforced on the actual send path — not just displayed as a countdown nobody checks before sending.
Audience, scheduling, launch approval, and full pause/resume/cancel work locally. Resume re-runs every guard the launch ran — permission, template gate, bridge-risk acknowledgement, consent sweep — and rolls back entirely if nobody left still consents.
Needs: A connected WhatsApp number for delivery.
Local CRUD plus pre-submission validation of the rules Meta actually enforces. Approval state comes back from Meta once a number is connected.
Needs: A connected WhatsApp Business Account for Meta approval and sync.
A flat step-list engine (no canvas, no branching) with an eleven-item template gallery, plus a natural-language builder: describe an automation in English, Hindi or Hinglish and get back validated steps, with any invented connector or action dropped and reported, and any missing required argument returned as a question instead of a guess. A published flow drives real inbound traffic too — the same evaluator the dry-run tester uses matches each customer message to the flow's next node, persists the contact's place in a session row so a process restart cannot lose it, and hands off to a human on reaching a handoff node; a sweeper expires sessions idle past 30 minutes back to the human queue so nobody gets stuck talking to an abandoned bot.
Needs: An LLM key for the description-to-steps builder. The template gallery, hand-built flows and live routing all work without one.
A short wa.me link with a tracking code embedded in the message text itself, since WhatsApp passes no referrer. First-touch attribution: attributing a click to a conversation a second time is a no-op, not an overwrite.
Booking, rescheduling (which shifts unsent reminders by the same delta) and cancellation all work locally. This route only computes what is due — sending the reminder needs a connected number.
Needs: A connected WhatsApp number to actually send a reminder.
Catalogue and product records work locally. Syncing a manual catalogue is refused outright (409) — there is nothing to sync from; syncing a Shopify/WooCommerce catalogue with no credential returns 200 with products_pulled: null, never a fabricated zero.
Needs: A Shopify or WooCommerce credential to actually pull products.
Cart capture and a three-step recovery schedule (1h / 1d / 3d) work locally and idempotently. Each step needs a connected number to actually send.
Needs: A connected WhatsApp number for the recovery messages themselves.
A number registry with an exclusive default flag works locally. Quality rating and messaging tier come from Meta and are never invented — an unconfigured workspace gets an honest note, not a plausible-looking number.
Needs: Meta credentials for live quality-rating and messaging-tier lookups.
Presentational fields (about, description, photo) apply immediately. Identity fields (name, address, email, vertical) stage into a pending set and need a second person — not the one who staged it — to approve.
Needs: A connected Meta account for the verified badge itself, which is Meta's to grant.
Connection registry and field mappings are stored and validated against a known-field allowlist. A config value that looks like a secret (api_key, token, password, ...) is refused outright — only a named credential reference is stored, never the credential.
Needs: The third-party provider's own credential to actually sync.
A guided checklist per provider stores a pasted App ID, secret and any other required field, encrypted at rest and never returned by any response. whatsapp/messenger/instagram/meta_ads, which share one Meta app, are verified against a live Graph API call before being marked verified; tiktok_ads and google_ads store the credential with no live verification probe yet.
Needs: A Meta, TikTok or Google developer app the customer owns and pastes the credentials for.
sent / delivered / failed / pending are always real, counted from our own recipient rows. read and clicked are Meta's figures and are always null without a connected account — never zero, since zero would assert nobody opened it. An hourly ingestion worker additionally pulls Meta's own template and pricing analytics into performance snapshots ahead of Meta's own retention window closing — built and tested against a fake Graph API response, though it has never run against a live account yet.
Needs: A connected WhatsApp Business account with Meta's business_management / whatsapp_business_management permission — granted only through Meta App Review, which Embedded Signup does not request today. Without both, the worker records why it skipped a workspace rather than writing a zero or an invented figure.
Form definition, server-side validation of submitted payloads, and routing of results — all against Wavy's own data.
API surface
Every route below is mounted and reachable today. Requests and responses are real shapes, not illustrations.
A free-form reply is checked against the service window before the provider is ever called. This refusal is the whole point of the window guard.
/api/v1/inbox/conversations/{conv_id}/messagesSend a free-form reply — refused with 409 if the window has closed.
Request
{
"body": "Thanks for waiting — here's your order status.",
"type": "text"
}Response
{
"detail": "The 24-hour service window closed at 2026-08-15T09:14:00+00:00. A free-form reply would be accepted by Meta and then dropped, so it is refused here instead. Send an approved template (GET /api/v1/templates, then POST /api/v1/campaigns for the send), or wait for the customer to message again — a new inbound reopens the window."
}/api/v1/conversations/{conv_id}/window-statusCheck the window before you rely on a free-form reply working.
Response
{
"conversation_id": "8f14e...",
"service_window_hours": 24,
"window_opened": true,
"is_open": false,
"last_inbound_at": "2026-08-14T09:14:00+00:00",
"closes_at": "2026-08-15T09:14:00+00:00",
"seconds_remaining": 0,
"free_form_allowed": false,
"template_required": true,
"reason": "Service window has closed; only a pre-approved template may be sent."
}/api/v1/inbox/conversations/{conv_id}/notesLeave a staff-only note. There is no route from a note to a customer message.
Request
{
"body": "Waiting on the customer's pincode before we can quote shipping."
}Response
{
"id": "3c2f...",
"conversation_id": "8f14e...",
"author_id": "usr_42",
"body": "Waiting on the customer's pincode before we can quote shipping.",
"visibility": "internal",
"created_at": "2026-08-16T10:02:00+00:00"
}/api/v1/campaigns/{campaign_id}/launchLaunch a draft campaign. Non-consented recipients are suppressed, not sent.
Request
{
"accept_bridge_risk": false
}Response
{
"id": "c-91a2",
"name": "Diwali collection preview",
"status": "sending",
"suppressed_without_consent": 500,
"daily_cap": 1000,
"remaining_today": 620
}/api/v1/consent/{contact_id}/opt-outOpt a contact out and cancel anything already queued for them.
Request
{
"category": "marketing",
"note": "Asked to stop on a call"
}Response
{
"contact_id": "ct_105",
"records": [
{
"category": "marketing",
"state": "opted_out",
"revoked_at": "2026-08-16T10:10:00+00:00"
}
],
"cancelled_recipients": 2
}/api/v1/templates/validateDry-run a template against Meta's own rules before spending a submission on it.
Request
{
"category": "AUTHENTICATION",
"body": "Your code is {{1}}. Visit example.com to verify.",
"buttons": []
}Response
{
"valid": false,
"violations": [
{
"rule": "auth_no_url",
"detail": "Authentication templates cannot contain a URL or a URL button. Meta rejects them, and a link in a one-time-passcode message is a phishing pattern."
}
]
}The vocabulary is two connectors and ten actions. An invented connector or action is dropped and named, never approximated.
/api/v1/automations/draftTurn a description into validated steps. Writes nothing.
Request
{
"description": "jab koi price puchhe reply kar do rates ke saath"
}Response
{
"name": "Reply to price questions",
"summary": "Send rates when asked.",
"trigger": {
"type": "message_received",
"first_message_only": false
},
"steps": [
{
"id": "check",
"connector": "control",
"action": "continue_if_any",
"arguments": {
"value": "{{ trigger.text }}",
"any_of": [
"price",
"rate",
"kitna"
]
},
"purpose": "check they asked about price",
"costs_money": false,
"is_destructive": false
},
{
"id": "reply",
"connector": "wavy",
"action": "send_message",
"arguments": {
"to": "{{ trigger.phone }}"
},
"purpose": "reply with rates",
"costs_money": true,
"needs_approval": true
}
],
"dropped": [
{
"connector": "email",
"action": "send",
"purpose": "email them the rate card",
"reason": "I could not find a way to email them the rate card. There is no 'email' in Wavy. What I can work with: control, wavy."
}
],
"questions": [
{
"step_id": "reply",
"argument": "body",
"question": "I still need the message to send for 'reply with rates'. What should it be?"
}
],
"ready_to_install": false,
"enabled": false
}/api/v1/automations/templatesThe eleven-item gallery — ten work today on the engine's own wait step; only the AI-drafted reply needs a key.
Response
{
"total": 11,
"available": 10,
"items": [
{
"slug": "after-hours-auto-reply",
"available": true
},
{
"slug": "reply-to-price-questions",
"available": true
},
{
"slug": "appointment-reminder",
"available": true
},
{
"slug": "recover-abandoned-carts",
"available": true
},
{
"slug": "ai-drafted-reply",
"available": false,
"reason": "needs the AI drafting step, which is not wired into automations yet"
}
]
}/api/v1/ai-agent/sessionsOpen a disclosed AI session. Cannot be created without a disclosure the customer saw.
Request
{
"conversation_id": "8f14e...",
"disclosure_text": "You're chatting with Wavy's AI assistant, not a person. Reply 'agent' anytime to talk to our team."
}Response
{
"id": "sess_77",
"conversation_id": "8f14e...",
"state": "active",
"disclosed": true,
"turns": 0,
"escalation_reason": null
}/api/v1/ai-agent/sessions/{id}/handoffEscalate to a person, instantly. Idempotent — asking again still succeeds.
Request
{
"reason": "customer_request"
}Response
{
"id": "sess_77",
"state": "escalated",
"escalation_reason": "customer_request",
"handoff_summary": "Customer: is there a person I can talk to?\nBot: Sure — connecting you now.",
"escalated_at": "2026-08-16T10:20:00+00:00"
}Limits and gotchas
A QR-paired handset has no Meta service window — it is a phone, and a phone can message anyone at any hour. Applying the 24-hour rule there would refuse replies on a rail that never had the restriction in the first place.
A worker pass already in flight holds the recipient list it fetched when it started and finishes those before stopping. Queued recipients not yet picked up are parked immediately.
Approver permission, template approval on the cloud rail, the bridge-risk acknowledgement, and the consent sweep all run again — consent withdrawn while paused is caught before anything is requeued.
The engine executes a flat step list, by decision. A description that implies a branch is compiled to the closest flat sequence the vocabulary supports, not a conditional graph.
Extra steps are truncated and reported, not silently dropped without a trace.
Both the gallery path and the described-automation path install with enabled: false. You preview it, then switch it on yourself.
Publishing is refused (409) if the flow has no handoff-type node at all, or if the handoff node is unreachable from the start — a bot loop with no way to reach a person is refused, not shipped.
Refreshing a number's health without Meta credentials configured returns the last locally recorded rating with from_provider: false and an explicit note — this deployment does not call Meta's Graph API for live lookups.
What this needs from you
Everything else on this page works with none of these connected.
| Credential | Unlocks |
|---|---|
| Meta WhatsApp Business Account | Actually sending: campaigns, appointment reminders, cart recovery, template approval and sync. |
| LLM_API_KEY | The natural-language automation builder (POST /automations/draft). The template gallery and the flow evaluator work without it. |
| Shopify or WooCommerce credential | Product catalogue sync. A manual catalogue cannot be synced by design — there is nothing to pull from. |
| A CRM provider's own API credential | Field-mapped sync to a connected CRM. Only a named credential reference is stored here, never the secret. |
Questions
No. A free-form send outside the window is refused with a 409 naming the template alternative, before anything is handed to a provider. This applies only to the cloud rail — a paired handset has no such window.
Not for a marketing-category template. Every queued recipient is checked against a category-matched consent record at launch and again at resume; a contact with no record is treated as blocked, never assumed.
It is dropped from the plan and named in the response with the reason — for example, naming a connector that does not exist. Nothing about the description is silently substituted with something close.
No. A note is stored as a different database table entirely, with no direction, provider id or status column — there is no code path that could send it.
Available today