ONE whatsapp:form-reply
← Receivers

whatsapp:form-reply

whatsapp family

Before a WhatsApp message outside the 24-hour window: is this person on record as agreeing to WhatsApp from the workspace that owns the business number (the lead form's tick), not opted out, and is the form-reply allowance free? Takes the allowance (one text or WhatsApp reply per number per workspace in 14 days, shared with sms:send form_reply; three a UTC day per number across every workspace) and answers the business name the template carries, so the message says who is writing. Only the channels WhatsApp door, carrying its fresh HMAC.

Effect
ask
Awaits an outcome — the call returns the response below.
Caller
write
The class of authority the caller must already hold, decided from the attested context with no round trip.
Cost
free
What one call costs, so you can budget before acting.
Reversible
no
This cannot be undone. Dry-run it first where the contract allows.
Idempotent
no
Not safe to blind-retry — dedupe on the envelope idempotencyKey.
Version
1.0.0
Pin this to keep a contract stable; additive bumps never break callers.

Send it with your agent

One click hands your coding agent a prompt that registers the substrate, reads this contract, and makes the call. Launch opens the app; the others copy the prompt.

Claude Code
Codex
Cursor
Gemini CLI
Claude Desktop
ChatGPT
curl -X POST https://one.ie/api/ask/whatsapp:form-reply \
  -H "Authorization: Bearer $ONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": { "phoneNumberId": <string>, "to": <string>, "at": <number>, "attest": <string> }}'

The key is never in a link. npx -y @oneie/cli login writes it to ~/.config/oneie/key on your machine.

Request

Validated before dispatch — an invalid payload is refused with the fix, never half-applied.

  • phoneNumberId string required The business number's phone number id — the workspace is read from it
  • to string required The customer's WhatsApp id (digits, no +)
  • at number required Epoch ms the door signed at; older than five minutes is not the door
  • attest string required The door's HMAC-SHA256 over phoneNumberId, to and at

Response

What comes back from the call.

  • ok boolean
  • workspace string
  • name string The business name the template's first parameter carries
  • error string forbidden · unattested · unknown_number · no_db · consent_declined · consent_unreadable · no_whatsapp_consent · already_replied · number_daily_cap · cap_unreadable

Traffic

Every call to whatsapp:form-reply, counted where it is dispatched — over HTTP or in-process alike. Aggregate only — no actor, no payload, no workspace.

Counting…

Wiring

Every place in the open source that names whatsapp:form-reply, and the file that answers it. Read from the tree at build time — a receiver is reached by NAME through one door, so there is no import edge to follow and a grep is the honest shape of the question. Structure, not volume — the count is in Traffic above.

Called from

API route 2
  • one.ie/web/src/lib/receiver-index.generated.ts:491
  • one.ie/web/src/lib/resolvers/whatsapp.ts:224
Agent runtime 2
  • channels/src/channels/whatsapp-cloud.ts:149
  • channels/src/channels/whatsapp-tenant.ts:25
→

Answered by

whatsapp:form-reply one.ie/web/src/lib/resolvers/whatsapp.ts:222 Dispatched through POST /api/ask/whatsapp:form-reply, after the envelope validates the payload.

whatsapp family · 2 more

JSON Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "phoneNumberId": {
      "type": "string",
      "description": "The business number's phone number id — the workspace is read from it"
    },
    "to": {
      "type": "string",
      "description": "The customer's WhatsApp id (digits, no +)"
    },
    "at": {
      "type": "number",
      "description": "Epoch ms the door signed at; older than five minutes is not the door"
    },
    "attest": {
      "type": "string",
      "description": "The door's HMAC-SHA256 over phoneNumberId, to and at"
    }
  },
  "required": [
    "phoneNumberId",
    "to",
    "at",
    "attest"
  ]
}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "workspace": {
      "type": "string"
    },
    "name": {
      "description": "The business name the template's first parameter carries",
      "type": "string"
    },
    "error": {
      "description": "forbidden · unattested · unknown_number · no_db · consent_declined · consent_unreadable · no_whatsapp_consent · already_replied · number_daily_cap · cap_unreadable",
      "type": "string"
    }
  },
  "required": [
    "ok"
  ]
}